[last update]
Add script command emailmsg, modify control command iferror
[AgeII] Add script command usecastleitem
[AgeII] Add config zerofood
Add goal valleytype
Script: gosub now supports parameters and local variables. gosubreturn can return a value
Security update, reduce memory leak from scripts
Update schedulepolicy
[AgeII] Attempt to support new type of hero and rally spot level 11+
Add config noautoquest
Update comfort cost, add config lookahead
[AgeII] Add goal colohints
Add internal field m_city.actionResponse to complement m_city.actionFactory
[AgeII] add config reservedenergy
Add goal valleyheroes, add config maxproduction
Fix comfort cost, change building wall during attack, add broken gate awareness
Support double build for both Age I and Age II

Restricted versions for farming only (with no captcha solver):
Download Age I Farming version 1.63 at fileswap
Download Age II Farming version 1.63 at fileswap

Elite version (most people should not use this version, no hacking or stealing please!):
Age I version 1.85 at fileswap
Age II version 1.71 at fileswap

Discussion: http://autoevony.cc

Please help IronHeart to edit Wiki page. While the documentation here is intended to show available features, it is not intended for general audience. The wiki hopefully contains more detail information as well as more practical help on how to get things done using the available features.


If you play at Evony for some time, you will notice that a lot of time you spend are on uninteresting tasks. The goal of this Evobot City Management is to remove as many of these tasks so that you can focus on what you are interested in. You can turn on the features you like, and turn off those that you do not.

Here are the main features:

  • Build and research based on goals you provide. Dependent buildings and researches are added automatically.
  • Trade automatically to balance out resources
  • Simple npc farming for resource
  • Hunt for medals automatically. Even on new servers, you can advance your title reasonably quickly.
  • Build npc level 5 automatically in the surrounding area of your towns.
  • Select good heroes from the Inn, train and upgrade them

There are also a number of combat related features:

  • Guarded attack allows troops to be recalled automatically if target is reinforced.
  • Loyalty attack makes sure at most one wave of cavalry dies in case the target is reinforced.

Specifying Goals

You can specify what you want your town to do in the Goals tab. No gui is currently provided, and the goals are specified in text.

Sample goals:

build sawmill:2:8
build cottage:2:4
build sawmill:2:12
build cottage:3:4,inn:2,academy:1
build lumber:3:12,cottage:4:4

research lumbering:9,agriculture:4

troop a:1,warr:1,wo:1,p:1,sw:1,cav:1,cata:1,ram:1,cp:1
troop a:100000,b:550,t:400,warr:3000,wo:5000,s:0,p:200,sw:200,cav:1,cata:1,ram:1

fortification trap:1,ab:1,at:1,r:1,rock:1
fortification at:1000
fortification trap:100,ab:100,at:14000,r:10,rock:10

config trade:1,hero:11,buildnpc:5,dumping:1
Build goals are used to specified the building, level, and the quantity you like. A build goal like "build sawmill:2:8" means you want 8 saw mills level 2 (or higher). A build goal with level 0 has special meaning and is used when you want to demolish buildings. A goal like "build cottage:0:8" means that you want to demolish and keep at most 8 cottages. The quantity is 1 by default, so a goal like "build academy:4" means you want one academy level 4.
Special note:Inn is treated specially. "build inn:3" means "upgrade/demolish the inn until it has level 3".

Building names are among academy, barrack, beacon, cottage, embassy, feasting, forge, farm, sawmill, quarry, iron, inn, market, rally, relief, stable, town, wall, warehouse, workshop. Research names are among agriculture, lumbering, masonry, mining, metal, info, militaryscience, militarytradition, ironwork, logistics, compass,horseback, archery, stockpile, medicine, construct, engineer, machinery, privateer. Refer to evobot for more ways to name buildings and researches.

Note that you can specify a building goal like academy without specifying other buildings that must be built before an academy can be built. These required buildings are added to the goals, in this case, town hall level 2 becomes a goal automatically. Similarly, you can specify cottages level 4, which implicitly requires town hall level 3, which requires wall level 1, workshop level 1, forge level 2, iron mine level 3, all of which are added to the goals.

Note also that research and buildings may be dependent on each other. Asking for a building will make the research that building depends on to be researched, and asking for a research will make the buildings that the research depends on to be built.

When having only research lines, you may want to turn on building with "config build:1" so that dependent buildings are built as needed. Similarly, when having only building lines, you may want to turn on research with "config research:1".

Troop goal and fortification goal are used to specify the troop and fortification you want. The troop type must be one of the following wo for worker, warr for warrior, p for pikemen, sw for swordmen, s for scout, a for archer, cav for cavalry, cata for cataphract, t for transporter, b for ballista, ram for battering ram, cp for catapult.

The fortification type must be one of the following trap for trap, ab for abatis, at for archer tower, r for rolling log, rock for trebuchet.

Troops are normally produced in small quantity to allow quick change. The hero used is the best available attack hero at the time the troops are queued.

A separate troop production may be started when there are plenty of resource. You can enable this secondary production line using "config dumping:1", or more generally "config dumping:factor", where factor is a number. The bot will queue troops in larger batch. The hero used to produce this batch will always be your best hero in town, and the bot will always wait for his hero before queuing troops.

You can alternatively specify a good hero to be used when dumping troops with

traininghero heroname [minStayingTime]
Ex. traininghero Bob
Ex. traininghero Bob 300
The bot will wait for this training hero before queuing troops. Note however that the bot may reserve one barrack to produce troops in emergency situations, and keep the queue there short. The troops produced in that reserved barrack may or may not be the training hero specified.

It is desirable to have a super hero to train troops in many towns. In that case, the bot will automatically compute a route for your super hero. Note that "nexttrainingpos" is no longer used. The best hero is too important, while it is too easy to make mistake specifying the training route manually.

If you use the same traininghero in many town, the bot would send the traininghero repeatedly through the town. To slow down the pace, you must tell the bot to stop the hero by adding the hero in the npc10heroes list. You can optionally specify your desired time for the bot to loop through your towns with "trainingLoopTime seconds", for example "trainingLoopTime 7200", to ask the training hero to go through all the towns approximately once ever 2 hours. If a minStayingTime is specified in the traininghero goal, the bot will also make sure that the hero does stay in the town for no less than the time you specified (in seconds).

For advanced users, it is possible to build troops conditioning on the troop level on another town.

extratroop xxx,yyy a:1000000 a:650000
  to traing 650k archers when xxx,yyy has less than 1m archers
extratroop xxx,yyy s:1000000,a:2000000 s:400000,a:650000
  to traing 650k archers when xxx,yyy has less than 2m archers
  or to traing 400k scouts when xxx,yyy has less than 1m scouts
Note that "extratroop", together with "keeptroop" and "requesthelp", enables linking the defense of all your towns together. A simple way to set up is to have one main town and many production towns, with the production towns sending troops and resources to the main town, and the main town help back the production towns with troops and resource if necessary.

It is desirable sometimes to slow down troop training so that your town has enough population for resource production. You can add "config maxproduction:1" in that case. The bot will then only use population that is truly idle when training troops. The "config maxproduction:1" is automatically ignored if the town is under attacked.

High level tasks

You can use config lines to automate many different tasks. Each task can be put on a separate config line, or a few tasks can be specified on a single config line.
  1. Trade
    • Use "config trade:1" to enable trading. You should have a market and have trading enabled to allow the bot to manage resource. Virtually all tasks require resource and unless you are around all the time to manage the resource manually, you should have this feature on. Even if you don't like the way the bot manages resource, you should still have this feature on.

      If you wish the bot to trade more, especially when your town's resource is low, or your resource consumption is high, use "config trade:2". To force the bot to trade even more, use "config trade:3".

      You can optional tell the bot your desired resource with "resourcelimits food1,food2 lumber1,lumber2 stone1,stone2 iron1,iron2", for example "resourcelimits 2m,4m 2m,12m 2m,1b 2m,12m". The first set of numbers in the 4 pairs is used as the resource that you need, and the second set is used as the resource that you want. You can use "k", "m", and "b" to denote "thousand", "million", and "billion" respectively. The bot will get what you need first, then get what you want. For backward compatibility, if you only specify one number for each of the resource (instead of pairs of number), the bot will treat the values as what you want. You can optionally ask the bot not to trade a resource (say if you want to keep food at 0 in Age II) by using the pair 0,0 for that resource in the resourcelimits.

      For lumber/stone/iron, if you set the upper limit to a value lower than the storage capability of your town, the bot will sell the resource beyond the upper limit for gold, even when the town does not need any other resources. If the upper limit is above capability, the bot will not sell the resource unless it needs gold to buy something else.

      The bot normally try to keep enough food to feed troops for 1 day. The food above may be sold to buy other resources as needed. You can ask the bot to keep more food on reserve with config extrafood, for example "config extrafood:2" to have 2 extra days of food on reserve (in addition to the default 1 day). Be careful as the bot may stop many of its tasks when the unreserved resource is low or negative. In AgeII, you should keep the food reserved low, for example with "config extrafood:-0.9", or have no food reserved at all with "config extrafood:-1".

  2. Heroes management
    • Use "config hero:1" to uplevel your heroes and do nothing else.
    • Use "config hero:10" if you wish to have 1 good politic hero and the remaining are attack heroes.
    • Use "config hero:11" if you wish to have 1 good politic hero, 1 good intel hero, and the remaining are attack heroes.
    • Use "config hero:12" if you wish to have 1 good politic hero, 2 good intel hero, and the remaining are attack heroes.
    • Use "config hero:20" if you wish to have 2 good politic heroes and the remaining are attack heroes.
    • Use "config hero:21" if you wish to have 2 good politic heroes, one good intel hero, and the remaining are attack heroes.
    • Use "config hero:22" if you wish to have 2 good politic heroes, 2 good intel heroes, and the remaining are attack heroes.
    • You can add "config fasthero:level", for example "config fasthero:60" to let the bot rapidly hires and fires heroes to speed up the hero selection from the inn. This option requires gold, and should be suitable only when you have a low level inn. The hiring/firing ends when all attack heroes have base attack value above the level specified.
      [AgeII] When level is from 1-9, the heroes are selected according to the hero level instead. For example, with "config fasthero:5", the bot will attempt to keep only heroes with level 50+. Make sure you have high level Inn in this case.
    • The bot normally keeps one politics, and one attack hero around, and if you have research enabled, one intel hero. If you wish to train your heroes with NPC farming, be sure to have 2 heroes of the type(s) you wish to train. When building/researching/producting troops, the bot makes sure that the appropriate hero is the mayor. If you enable "config training:1", the highest attack hero will be sent on npc farming missions, and the 2nd highest attack hero is kept around for troop production.
    • There are times when you absolutely don't want to keep any captured heroes. Use "config nocapture:1" to force the bot to release all captured heroes automatically.
    • If you want the bot to remove the mayor when the mayor is not needed (say after troop training), use "config nomayor:1". The bot normally appoints mayor as needed. When the town is idle, the bot would remove the mayor with nomayor config on, otherwise appoint a politics hero with hero config on.
    • The bot normally uplevels heroes automatically. You can disable such behavior for selected heroes with "nouplevelheroes", for example "nouplevelheroes Bob,Max"
    • When selecting political and intel heroes, you can tell the bot to disregard those with low attack values (as they are hard to train later) by specifying config "herominattack". A "config hero:20,herominattack:40,fasthero:65" tells the bot to look for 2 politics heroes with 65+ politics and 40+ attack attributes.
    • You can optionally tell the bot to reserve feasting hall slots with "config fhreserved:number", for example "config fhreserved:2" to tell the bot to leave 2 feasting hall slots empty.
  3. NPC farming, level 1-5
    • Use "config npc:1" to farm npc level 1 to 5
    • Use "config npc:2" to farm npc level 2 to 5
    • Use "config npc:3" to farm npc level 3 to 5
    • Use "config npc:4" to farm npc level 4 to 5
    • Use "config npc:5" to farm npc level 5 only

    Note that "config npc:10" is invalid. NPC 10 farming is enabled via "npc10limit" instead.

    The number of transports are computed automatically from your research level. The number of ballistas used are chosen as "safe", though from time to time, you may experience ballista lost. To change the number of ballistas used, use a "ballsused" line to specify the number of ballista you would like to use to attack npc level 1 to 5.

      ballsused ball1,ball2,ball3,ball4,ball5
      Ex. ballsused 20,50,130,200,400
      [default] ballsused 20,50,170,250,550
    You can further modify the behavior of npc farming. Note that this may interferes with the normal operation of the bot.
      npclist 101,102 101,103 101,104 102,102
      npcavoidlist 101,102 101,103 101,104 102,102
        to avoid a selected number of npc's
      npcarea 90,90 110,110
        to restrict the farming to npc's inside an area defined by its 2 corners
        area can wrap around the map boundary, for example "npcarea 10,10 790,790" 
      npcheroes Bob,Bing,Ives,Tracy
      notnpcheroes Bob,Bing,Ives,Tracy
        when both npcheroes and notnpcheroes are present, notnpcheroes is ignored.
      npctroop b:400,t:400,warr:1000
    You can specify the list of npc on multiple npclist lines. List of npc's can be obtained from with the program, see findfield command.

    You can use "config npclimit:days", for example "config npclimit:7" to limit the npc farming. The bot will stop farming when the amount of food exceeds what your troops use in the number of days specified.

    When the limit for npc has reached, you can continue NPC farming to train your heroes. The npcs are then hit every 1 hour as resource is no longer the goal. Use "config training:1" or "config training:2" for this purpose. With "training:1", the resource can be substantially above the limit set in npclimit. With "training:2", the npc training attacks are guaranteed not to increase resource. The heroes are trained much more quickly when npclimit is on and the resource limit has reached. When the value of "config training" is 6 or higher, the bot takes the value as the frequency (in minutes) that you want to hit any particular npc, so use "config training:30" means hitting npc every 30 minutes when npclimit has been met.

    At any time, you can run inline command "\qfarm" to send all the farming waves out. On server with captcha, you can use "config qfarm:1" to run \qfarm automatically whenever you solve the 1k-resource captcha.

    You can use goal rallymax to further influence npc farming, for example "rallymax npc:6" to limit the number of npc farming waves to 6 or less. Check rallymax section for more information.

    On servers with captcha, you can use farmingthrottle, for example, "config farmingthrottle:2" to slow down the farming whenever the bot sees the 1k resource bonus package. farmingthrottle default value is 1 (hour). Without throttling down the farming, the captcha appears once every 5 minutes and the bot behavior may be too unreasonable.

  4. Attacking NPC level 10
    You will lose troops if you wish to attack NPC level 10. While resource should best be obtained by farming NPC level 5, you may want to attack NPC level 10 if you want to level up your hero faster. To attack NPC level 10, you need to enable it with
    npc10limit troops
    Ex. npc10limit a:200000,warr:50000
    The bot will start attacking NPC level 10 once your troop is above the limit specified. By default, the troop attacks npc level 10 with the best hero in town and about 90k archers, 2k warriors and workers, 4k scouts, 1.9k transports, and 1 pike/swords/cavalry/cataphract. You can change customize NPC 10 attacks with npc10list, npc10heroes, and npc10troop, for example:
      npc10list 101,102 101,103 101,104 102,102
      npcavoidlist 101,102 101,103 
      npc10area 90,90 110,110
        to restrict the farming to npc's inside an area defined by its 2 corners
        area can wrap around the map boundary, for example "npcarea10 10,10 790,790" 
      npc10heroes Bob,Bing,Ives,Tracy
      npc10troop a:91100,warr:2000,wo:2000,s:3000,t:1900
    By default, the bot attacks an NPC 10 once every 8 hours. To ask the bot to attacks the NPC once every hour, use "config training:1". Note that unlike in NPC 5 farming, npclimit config has no effect on NPC 10 farming.

    You can use goal rallymax to further influence npc farming, for example "rallymax npc:6" to limit the number of npc farming waves to 6 or less. Check rallymax section for more information.

  5. NPC farming, all levels You can have more details control over npc farming with one or more goals "priorityfarming". The priorityfarming goals are processed one by one in order of their appearance, and are processed before the farming enabled by "config npc" and "npc10limit".

    priorityfarming takes a minimum of 3 parameters: the level of the npcs you want the bot to farm, the minimum number of the troops you want in your town before the farming can take place, and the troops you want to farm the npcs with. You can optionally specify the farming radius, the frequency you wish to farm the npcs, and the heroes the bot must use for the farming. You can have multiple priorityfarming rules, including multiple rules for the same npc level.

    priorityfarming level trooplimit farmingtroop [radius] [frequency] [heroList]
    Ex. priorityfarming 8 warr:200000 warr:98800,t:1200 10 480 hero1,hero2,hero3
    Ex. priorityfarming 10 a:500000 a:95000,s:5000 5 60 SUPERHERO
    Ex. priorityfarming 10 a:800000 a:90000,wo:2000,warr:2000,s:4000,t:2000 12 480 any,!SUPERHERO,!#pol,!#int,!DEFENDER
    Ex. priorityfarming 5 b:400,t:400 b:400,t:400 40 480 any,!SUPERHERO,!POLYHERO,!DEFENDER
    In the above example, the bot would farm npcs level 8 within 10 miles once every 480 minutes when the town has more than 200k archers, hitting the npc with 98.8k warriors + 1.2k transports with hero hero1, hero2, hero3. It also farms npcs 10 once every 60 minutes with SUPERHERO, and once every 480 minutes with any heroes that are not named "SUPERHERO" or "DEFENDER, and is not the best poly or intel hero in town. It also farms npcs 5 with heroes that are not "SUPERHERO", "POLYERO", or "DEFENDER".

    Note that the herolist specification in priorityfarming is the same as that in script commands like "attack" and "reinforce". You can name the heroes one by one in the hero list, or with "any", follow by ! and the excluded heroes. You can also use generic hero names like "#pol", "#pol2", "#int", "#int2", "#absbest", "#best", "#worst".

  6. NPC building
    • Use "config buildnpc:5" search for flat level 5 in surrounding area, attack the flat, and build npc from that flat. This task will only be carried out if you have enough troop for the attack (800 archers and 2.5k warriors), and enough resource and a city slot to build city. NPC of other levels can be built similarly, so "config buildnpc:10" would build NPC level 10. For backward compatibility, "config buildnpc:1" still builds NPC level 5, and thus there is no way to build npc level 1 with buildnpc config.
      "valleyheroes" can be used to specify the heroes used to take flats

      Three other special values can be used for buildnpc config. Use "config buildnpc:20" to convert all flats to npc regardless of levels, "config buildnpc:21" to convert all flats 5 or below (useful in Age II only). Use "buildnpc:15" to build npc level 5 and 10, npc 10 within 3 miles radius, and npc 5 between 3 and 10 miles. You can use "distancepolicy" goal line to change the distance thresholds.

      If you have config "buildnpc" on and not "valley", you can optionally enable "config flatrolling:radius", for example "config flatrolling:5". The bot will roll the flats within the radius you ask, by attacking the flats after maintenance, hold them, then release them back before maintenance, until the flats are at the desired level to build. The number of flats rolled is determined by the number of available valley slots in your town -- you need to abandon more non-flat valleys if you want the bot to roll more flats. This feature is useful only in Age I, and when you don't want your neighbor (especially bot neighbors) to build npc near your towns.

      You can use goal rallymax to further influence buildnpc, for example "rallymax buildnpc:2" to build 2 npcs at once. Check rallymax section for more information.

  7. Capture valleys for production bonus
    • Use "config valley:10" to search for valleys and occupy them to receive production bonus. Currently the bot focuses on only one type of valley to maximize the bonus. The type of valleys depends on your resource fields. If you have have more saw mills than farms, quaries, iron mines, for example, the bot will take only forest valleys.

      The valleys taken depend on what are available around you as well as your troop level. If you wish to take only valleys below a certain level, say level 5, you can specify "config valley:5".

    • You can use goal rallymax to influence valley capturing, for example "rallymax valley:4" to limit the number of concurrent attacks on valleys to 4. Check rallymax section for more information.
    • "valleyheroes" can be used to specify the heroes used to specified the heroes used in the valley capturing waves.
    • "valleytype", for example "valleytype lake,grassland,swamp" can be used to overide the default valley type.
  8. Hunting for medals
    • On old servers, use "config hunting:1" to attack valley level 1-3 for cross, rose, and lion medals. It can also be used to get honor, courage, wisdom, and freedom, though the drop rate is lower. Use "config hunting:2" and "config hunting:3" to attack valleys level 4-6 and 7-9 respectively for medals.

      If you are patient, you should be able to get your title to Duke by attacking level 1-3 valleys (and take no troop lost).

    • On new servers, the drop rate is much lower for low level valleys. There is pratically no medal from level 1-3 valleys. It is preferable to attack level 9 and 10 valleys for medals. Use "config hunting:4" to attack valleys level 9-10, and use "config hunting:5" to attack only valleys level 10. Be sure to have 20k+ archers and 60k+ warriors and a few of all other troops to attack level 9 and 10 valleys.
    • The server uses 50, 100, 200, 400, 800, 1600, 3200, 6400, 12800, 19990 archers in the attacks at the valleys, depending on its level. For valley level 4 and above, it also uses one warrior, scout, pike, swordman as layers. For valley level 6 and above, one ballista is also used.

      Expect to lose about 300k-400k archers to get your title up to Furstin. If your account is new and cannot afford to lose troops, the prefer method is to hunt for medals without losing much troops with "config slowhunting:4" or "config slowhunting:5".

    • "valleyheroes" can be used to specify the heroes used to specified the heroes used in the medal hunting.

      You can change the default setting for hunting with the following lines:

         valleytroop troop
         Ex. valleytroop a:50000,p:100,sw:100
         huntingpos location
         Ex. huntingpos 110,100
         huntingtype field_type
         Ex. huntingtype Desert,Hill,Lake
      The hunting location can be obtained via findfield command.

      You can use goal rallymax to influence medal hunting, for example "rallymax hunting:4" to limit the number of concurrent attacks on valleys to 4. Check rallymax section for more information.

  9. Lossless hunting for medals (SLOW!!!)
    • This feature is intended for new accounts with few troops. It is very restricted (cannot be used with config buildnpc, config hunting), only works when the valley slots are full, and is slow to start up. The positive side is that, you can hunt medals with very little or no loss, and that you can carry back the resources in the valleys you attack.
    • "valleyheroes" can be used to specify the heroes used to specified the heroes used in the medal hunting, for example "valleyheroes any+60,!BigDude"
    • The feature itself is complicated, but the control is simple enough. All you have to do is to set config "slowhunting", for example "config slowhunting:4". The slowhunting config value is 1-5, with 1 for levels 1-3 valleys, 2 for levels 4-6, 3 for levels 7-9, 4 for levels 9-10, and 5 for level 10.
    • Certain settings for slowhunting can be changed with "slowhuntingpolicy frequency w/p/sw_troop a_troop cav/w/p_troop cav/w_p_dist". It should only be set once you you've seen how the bot hunts for medals. For example "slowhuntingpolicy 30 a:20000,p:1,sw:1 none b:1,p:1,sw:1,wo:1,warr:1,a:20000 4" tells the bot to attack each valley once every 30 minutes, attack valleys with warr/pike/sword with 20k archers and 1 pike/sword, avoid valleys with pure archers, and hit valleys with cav/warr/pike within 4 miles with 20k archers + rainbow.

      You can also restrict the hunting with:

         huntingtype field_type
         Ex. huntingtype Desert,Lake,Hill

      You can use goal rallymax to influence medal hunting, for example "rallymax hunting:4" to limit the number of concurrent attacks on valleys to 4. Check rallymax section for more information.

  10. Comfort
    Use "config comfort:1" to let the bot to comfort your town. This is useful in a number of situations, making your town extremely hard to be captured (especially when used with "config hiding:1"), or allowing your town to have few cottages, for example. If high prestige is desirable, you can use "config comfort:2" instead. To let the bot to have full control, you can use "config comfort:4". The bot will pick the comfort type most appropriate for your town. Once you have a high attack hero and wish to build troops quickly, "config comfort:4" is strongly recommended to let the bot comforts the town for population.

    The bot controls the tax rate if you enable comfort. If you don't want the bot to change your tax rate, you must disable comfort. If you enable comfort, you can optionally use "config mintaxrate:number", for example "config mintaxrate:20"to tell the bot to keep the tax rate at 20 or more.

    Keep in mind that the tax rate is linked with your town's population growth rate. You reduce your population growth rate if you set a minimum tax rate.

  11. Gate control
    Use "config gate:1" to let the bot to control the gate. The bot will open/close gate 1 minute before an attack to defend the town. In general, use "config gate:min", for example "config gate:0.2" if you want a different gate response time.

    The bot recognizes 5 situations, no attack, regular attacks, scout bombs, mixed attacks, paused (as in maintenance) and open/close the gate depending on what it thinks is best. You can tell the bot what to do more specifically by adding line "gatepolciy peace regular scbomb mixed paused [confidence]" in your goal after setting gate config, for example, "gatepolicy 0 1 0 2 0 6". Each of the first 5 numbers is for a situation listed above, with 0 means the bot is in charge, 1 means always open the gate, and 2 means always close the gate. The confidence value is optional and is used only when you leave the bot in charge of the gate, for example when you set attack value to be 0. The confidence should be between 1 and 10, with the default value of 4. The smaller the confidence, the more conservative the bot is. Recommended value for confidence is between 4 and 7.

    An additional gate policy number 3 can also be used for attack value. The gate behaves just like 2 in most cases. For regular attack and when rainbow hiding is on, the bot may open the gate if it is sure it can win with minimal cost. The gate behavior is purposely unpredictable with this option 3.

    You can also have one or more "conditional gate policy". A conditional gate policy has the form "condgatepolicy troop forification peace attack scbomb mixed paused [confidence]", for example, "condgatepolicy a:400000,p:1,sw:1 trap:1 1 0 1 0 1 0 6" tells the bot to use gate policy "1 0 1 0 1 6" whenever the town has at least 400k archers and 1 pike/sword/trap. Use "none" for troop or fortification when you don't want to specify constrain there.

    When multiple condgatepolicy lines match to the current situation, the first condgatepolicy line is used. Only when none of the condgatepolicy matches, the line "gatepolicy" is used or "gatepolicy 0 0 0 0 0 0" if gatepolicy is not specified (the confidence 0 means default confidence, which is 4).

    As an example, you can have gate policy to change depending on your troop level with:
    condgatepolicy s:200000,a:400000 none 1 1 1 1 1
    condgatepolicy a:400000 none 0 1 1 1 0 6
    condgatepolicy a:200000 none 0 0 0 0 0 5
    condgatepolicy a:50000 none 0 3 2 2 0 4
    gatepolicy 2 0 0 0 2 1

    When the bot opens gate, it sends out troops that may die needlessly. You can tell the bot how many rally slots it should reserve to move the troops out with goal "rallymax", for example "rallymax rainbow:2". To disable rainbow hiding, you can use "rallymax rainbow:0". Check rallymax section for more information.

    It is important that you have light rainbow or to have rallymax rainbow setting appropriately. If you purposely have a lot of rainbow troops and do not wish the rainbow troops to move out, you must set the confidence level in the gate policy high (say 8-10) for the bot to open the gate.

    When controlling gate, the bot looks for attacking waves within a period of about 4s. If your computer has plenty of CPU power available *and* you worry about long network lag, you could increase this look ahead time with config lookahead, for example "config lookahead:6". You can also reduce this look ahead time, say "config lookahead:2", if you wish the bot to treat more attacking waves as "attack" or "scout bomb" waves instead of "mixed attack" waves.

    In Age II, if your gatepolicy is auto, you can also use goal "colohints" to change override gatepolicy for the colonization and suppression battles. For example
    colohints 2 1 (close gate on colonization but open on suppression)
    colohints 7 10 (change confidence to 7 on colonization, 10 on suppression)
    The first value in colohints is for the colonization battle, and the second is for the suppression. Each value is between 0 and 10, with 0 means no modification (no gatepolicy change), 1 - open gate, 2 - close gate, 3+ temporarily override the confidence value of gatepolicy with this value.

  12. Monitor war reports
    Use "config warreport:1" to let the bot periodically check the war reports. The bot will notify if alliance members were attacked. This option is only available for your first town or town declared with "maintown".
  13. Audio Attack Warning
    Use "config attackwarning:1" to alert you with audio when your town is under attack. The bot ignores junk attacks, though. This option is only available for your first town.
  14. Email Attack Warning
    Use "config emailwarning:30" to send you an email (via forums) alerting you when your town is under attack. The value of email warning is the minimum time between successive emails sent to you.
  15. [Age2] No food operation
    Use "config zerofood", for example "config zerofood:5" when your town is about to run out of food because you have too many troops for the town to feed. Your town must be set up as if it is with enough food, and it must have at least one valley. With config zerofood, the bot will stop trading food (but continue to trade other resources as normal -- make sure you set resourcelimits appropriately for your town to convert extra resources to gold). When the food remaining in your town falls below the limit (5 hours in the above example) and if your town has transports, the bot starts to move food out to the nearest valley, leaving the town with no food, and from time to time recall the food. The bot can continue to farm npc and to train troops if you have config dumping on beyond its capability to feed them continuously.

    Unless all your towns are out of food, towns with zero food will draw the food from towns having food.

    When the network is lagging, the bot may not be able to send out food successfully and all your food may get lost. Make sure you have enough gold in your town for the bot to attempt to buy food and to restart the food hiding. If you have a lot of troops, you may disband a few manually to kick start the food hiding.

    Towns with zerofood can operate properly when there are more food in the town than the limit set by "config zerofood". When the food is low and food hiding starts to happen, the bot only keeps essential tasks running, in particular npc farming and troop training.

  16. [Age2] Autogear
    Use "config autogear:1" to allow the bot to change hero gears on a number of cases when the benefit of such change is obvious (say when the bot needs to train troops but the mayor is not on attack gear). For idle heroes, the bot would put on gear matching the hero type. "config autogear:2" works similarly, except all idle heroes use attack gear.
  17. [AgeII] Reserved energy for heroes
    Farming and various operations in the goal can deplete the energy of heroes. By default, the bot uses only heroes with 8 or more energy. You can modify this behavior with config reservedenergy, for example "config reservedenergy:40", to tell the bot to use only heroes with 40+ energy.
  18. Miscellaneous configs
    The bot by default delete most reports, keeping only essential ones. You can use "config keepreports:1" to disable this behavior. Use "config keepreports:2" to keep essential reports together with interesting ones (with troops lost and medals gained). In age II version, you can use "config junkhero:value", for example "config junkhero:2", to tell the bot the worst 2 heroes should be fired when their energy is too low. This is useful if you wish to run spam attack, fight valley war, or medal hunting, or situations where hero energy prevents you from sending out your attacks. If you use this option, make sure you set the "config hero" to reflect the number of politics/intel heroes you wish to keep in your town. If npc farming is too dangerous during maintenance (due to the removals of npc), you can ask the bot to recall npc farming around maintenance with "config safemaint:1".
  19. Schedule running time
    Use "schedulepolicy" to let the bot rests. As an example, use "schedulepolicy 18:30 0:30 6:00 12:00" to let the bot works from 6:30PM to 12:30AM, then from 6:00AM to 12:00PM. To make the times look random, the bot perturbs all the times randomly by 5 minutes, so in the above example, the bot actually connects to server at some time bewteen 6:25 and 6:35PM, and disconnects at some time between 12:25AM and 12:35AM.
  20. Distance policy
    Use "distancepolicy x x x x x", for example "distancepolicy 10 15 6 15 5" to modify the distances used in config npc (for npc farming), config buildnpc (for build npc), config hunting (for medal hunting), config valley (for valley resource bonus), and extra radius needed for buildnpc:15. If you set a distance to 0, the bot will use the default value. The default distance policy is "distancepolicy 10 10 10 15 3".

    Build NPC behavior is now determined by 2 radii when building npc 5 and 10 concurrently with buildnpc:15. The bot builds npc 10 inside the small circle, and build npc 5 in the ring between the 2 circles. For all other value of buildnpc, the small radius is ignored.

  21. Maintenance policy
    Use "maintpolicy x x", for example "maintpolicy 90 120" to modify the time the bot sleep after maintenance. The bot will sleep a random time within the range provided, in the above example, randomly between 90 and 120 minutes. The town with maintenance policy must be declared with "maintown" or the policy would be ignored.
  22. Enemy warning
    Use "config enemywarning:radius", for example "config enemywarning:5" to let the bot to notify you about enemy towns near your town.
  23. Troop Keeping:
    You may want to restrict a number of troops in a town, especially ones with limited food supply. Exessive troops can be sent somewhere else automatically with one or more lines of "keeptroop" or "keeptotaltroop". This feature is also useful to reinforce a war town or a town where you train hero with npc 10 attacks.
         keeptroop coord troop mincount
         keeptotaltroop coord troop mincount
         Ex. keeptroop 101,102 a:150000,warr:40000 10000
         Ex. keeptotaltroop 101,102 b:5000 200
    In the first example, when there are more than 150k archers or more than 40k archers (in the Avail column of the troop tab), and that the number of excessive troops is 10k or more, the excesive troops are sent to 101,102. In the second example, when there are more than 5200 ballistas total in your town (including the ballistas what are out farming), the ballistas above the 5000 limit are sent to 101,102.

    keeptroop attempts to keep the troop currently available to your town below the amount you ask, while keeptotaltroop attempts to keep all troops available (which is the current troop + incoming reinforcement + troops currently out attacking) below the amount.

    You can use goal rallymax to influence keeptroop, for example "rallymax keeptroop:3" to allow at most 3 waves of keeptroop from this town. Check rallymax section for more information.

  24. Resource Keeping:
    You may want to limit the resource in a town and send excessive resource to a different town with with "keepresource". The feature could be useful if you have specialized towns and wish to automatically transports excess resource between them or to supply food to your war town.
         keepresource coord resource mincount
         Ex. keepresource 101,102 f:1000000000 50000000
    In the above example, when there are more than 1b food in the town the bot will try to send food to 101,102. The bot may have to wait for enough transports to make sure that each trip carries at least 50m resource.

    You can use goal rallymax to influence keepresource, for example "rallymax keepresource:3" to allow at most 3 waves of keepresource from this town. Check rallymax section for more information.

  25. Request Help:
    Request help is similar to troop and resource keeping, but in the reversed direction. A town can request troop and resource help when its troop and resource level falls below a certain level.
         Ex. requesthelp coord mintroop exttroop minresource extresource [warCond]
         requesthelp 101,102 a:400000 a:1000000 f:300000000 f:1200000000
           to have 101,102 send archers to this town when the town has less than
           400k archers and 101,102 has more than 1m archers, and to send food
           if this town has 300m or less food while 101,102 has more than 1.2b food.
         requesthelp any a:400000 a:1000000 f:300000000 f:1200000000
           request troop/resource from any other towns (this is the short hand
           for having many requesthelp lines, one for each of the other towns)
         requesthelp 101,102 a:200000 a:300000 f:0 f:0 true
           request troop from 101,102 if (1) this town is under attack and has
           less than 200k archers and (2) 101,102 is not under attack and has
           more than 300k archers.
    You can use goal rallymax to influence requesthelp, for example "rallymax requesthelp:4" to allow at most 4 waves of requesthelp from this town. Note, however, that a requesthelp goal is influenced by the the rallymax setting for requesthelp on the helper town. Be very careful when changing "rallymax" default values for requesthelp. You can be clueless when requesthelp does not work because the rallymax setting is wrong on another town!!!
  26. Hiding resource
    Transports and ballistas are important for your town to obtain resources. Use "config hiding:1" let them avoid battle, as well as to move your resource out before your town is attacked. This feature is useful when your town is extremely weak. When there are a lot of archers in the town, hiding does nothing. In general, you can use "config hiding:min", for example "config hiding:2.5" if you want to change the evaculation starting time.

    You can use goal rallymax to influence hiding behavior, for example "rallymax hiding:2" to allocate 2 rally slots for resource hiding at all time. The bot is free to send out as many waves as the rally permits, though.

  27. Auto use item
    For items that you can apply with script command useitem, you can let the bot use them automatically whenever you have them. For example, use "autouseitems Double_Saw,Arch_Saw" if you wish to use those 2 items automatically.

    Three items are specially recognized by this goal, Speech_Text, Truce_Agreement, and Advance_by_A_Hidden_Path. To use Speech_Text and Truce_Agreement with autouseitems, you must specify the loyalty of your town, at which the bot should use the item, for example "autouseitems Speech_Text:6,Truce_Agreement:2" to tell the bot to apply speech text item at loyalty 6, and truce at loyalty 2.

    You can optionally tell the bot to truce not only by the loyalty of your town but also the town's situation with "autouseitems Truce_Agreement:loyalty:situation". The bot recognizes 4 special situations: (1) for being attacked successfully, (2) for simply being attacked, (3) for being scouted successfully, and 94) for simply being scouted. For example, use "autouseitems Truce_Agreement:60:1" to tell the bot to truce when the loyalty is at 60, or when the town lost a battle.

    The bot does not use Advance_by_A_Hidden_Path whenever someone applies one on your town. To tell the bot to use the item only whenever it needs to send troops out, use "autouseitems advance_by_a_hidden_path:1". If you only wish to use the item when the town is under attack and the bot needs to hide rainbow (instead of just farming), use "autouseitems advance_by_a_hidden_path:2".

    You can list all the items you wish to use in one autouseitems, or you can have multiple useitems line. If you have multiple lines, the bot will use an item whenever there is match.

  28. Manage relogin time
    When the bot is running and you log in manually, the bot by default pauses for about 30 minutes then resumes running. You can change the pause time by setting relogin config, for example "config relogin:60" to let the bot pause around 60 minutes.
  29. Abandon
    The bot by default heals your town so as to prevent your town from being captured whenever possible, even when you don't ask it to. While this is desirable, there are times when you deliberately want to give your town away. In that case, you can set "config abandon:1" as the only goal in that town. The bot will remove your wall defense, abandon your troops, lower your town's loyalty down to 0. In case you want to lower your town's loyalty manually, you can use "config abandon:2" instead. Lowering your town's loyalty can be accomplished by script command "levy" or "settaxrate" or both.
  30. NoRescue
    If a town is in danger of losing, the bot by default brings resource from other towns to that town to heal it. You can selectively disable rescuing a certain town by adding "config norescue:1" in that town's goal.
  31. No Auto Quest
    The bot normally checks if there is a completed quest available and if there is one, it will pick up the award automatically. You can use "config noautoquest:1" to disable this behavior. In case the server malfunctions, notifying the bot a quest is available when there is none, you can diable the quest award picking entirely with "config noautoquest:2". Quest award can be always be picked via script "completequests routine".
  32. Rallymax
    In a typical setting for a town, the bot may send troops out to do various tasks. Many tasks use a common resource: the rally slots. Complex coordination between the tasks is needed to make sure all tasks can be done.

    The bot should adequately handle the coordination in most cases. There are cases, though, when you wish your town to do better in a given task (at the expense of other tasks) through the allocation of the rally slots. You can limit the number of rally slots the bot allocates for the 9 most common tasks with goal rallymax. By default, the bot uses the following internal setting "rallymax npc:10,buildnpc:1,valley:1,keepresource:1,keeptroop:2,requesthelp:2,hiding:1,rainbow:1". You can override one or more rallymax setting, for example with "rallymax npc:6,requesthelp:4". If you don't set the rallymax setting for any given tasks, the default rallymax setting is used.

    You are strongly recommended not to change setting unless you really know what you are doing. You can disable certain tasks by failing to allocate rally slots appropriately for them or to allocate too many rally slots for other tasks.

    A special note on rallymax setting for rainbow and hiding: Hiding resource and rainbow is considered critical for the defense of your town, and the bot by default ALWAYS reserves rally slots for these tasks. If you wish a task (say requesthelp) to attempt to use all rally slots, you must explicitly tell the bot not to reserve rally slots for rainbow and hiding with "rallymax rainbow:0,hiding:0".

    The bot also treats rallymax settings for rainbow and hiding differently from all other rallymax settings. When hiding resource, the bot may disregard your rallymax hiding setting completely and sends out as many waves as it deems appropriate. The bot on the other hand keeps the number of rainbow below the rallymax rainbow setting at all time, effectively allows "rallymax rainbow:0" to be the way to disable rainbow hiding (and currently the only way to disable rainbow hiding).

  33. WarRallyMax
    You can ask the bot to temporarily use a different rallymax setting if you are under attack with rallymax. For example, use "warrallymax npc:4,rainbow:3,keeptroop:0" to tell the bot to temporarily use 4 rally slots for npc farming, and 3 slots for hiding rainbow troops, and to disable keeptroop when under attack. The normal rallymax setting is used again an hour after the last attack on your town.

    As rally spot slots become available only when troops sent out with normal rallymax setting return, do not count on the bot to have the rally slots as you tell it with WarRallyMax. This feature is confusing and dangerous if not used correctly.

    In general, you should tell the bot to increase the number of slots for rainbow, and reduce the number of slots for other tasks such as npc/requesthelp/keeptroop. Changing the number of slots for resource hiding with WarRallyMax should have a bad effect on the defense of the town and is strongly not recommended.

    The feature is mostly useful in 2 cases: (1) your town is attacked from far away, and (2) your town is under attack for a long period of time.

  34. ReservedHeroes
    The bot treats a number of heroes in any given town specially. These heroes cannot be fired via "fasthero" config or spend out on spamming attacks (unless you specifically ask the bot to with spammingheroes). By default, the reserved heroes depends your "config hero". For example, with "config hero:21", the reserved heroes are "#pol,#pol2,#int,#absbest", i.e. the best 2 politics heroes and the best intel and attack hero. You can override this default setting with goal "reservedheroes", for example "reservedheroes #pol,Super,Sandy".
    Queen/King and historical heroes are automatically reserved regardless of your setting.
  35. Reuse goal/script with Snippets
    You can define snippets of text in the Snippets tab. Each snippet has a name in square brackets, followed by arbitrary texts. For example, the following defines 3 snippets "MySnippet1", "MySnippet2", and "MySnippet3"
    config npc:5,hero:10
    resourcelimit 5000000 5000000 5000000 5000000
    include MySnippet1
    include MySnippet2
    You can use "include" in both goal or script tab to "cut and paste" that snippet into your goal or script, for example "include MySnippet1". Note that "include" can be used recursively, so a snippet itself can include one or more snippets.

    The snippets can be quite useful if you wish to reuse goal/script between different towns. It can make your goal/script complicated and hard to understand, though.

  36. Set and Condgoal
    Set and Condgoal are advanced features. They should be avoided by people who are not familiar with programming.

    You can define variables within the goal section with "set". Once defined, you can access value of the variables by placing %% around the variable names. For example, you can have:

    set main 100,100
    keeptroop %main% a:300000
    keepresource %main% f:100000000
    requesthelp %main% a:200000 a:600000 f:50000000 f:200000000
    so that you can change the keeptroop, keepresource, requesthelp target by changing the line "set main 100,100".

    "Set" goal itself can be quite complicated. For example the following goal sets variable "isMain" to true if the town is at location 100,100, and set "isStorage" to true if it is the 4th town in the town list.

    set townLocId $m_city.castle.fieldId$
    set townCoord {%townLocId%|800},{%townLocId%\800}
    set isMain {%townCoord%==100,100}
    set isStorage {$m_city.allCities.indexOf(m_city)$==3}
    Goal variables can be accessed from the script side via internal function m_city.cityManager.getVar.

    You can define goals that are conditionally effective with condgoal. For example, a goal like this

    condgoal %isMain% troop a:1000000
    condgoal {!%isMain%} troop a:200000
    is "troop a:1000000" if %isMain% is true, and is "troop a:200000" if %isMain% is false.

    You can even have goals like these once you've defined snippets goal_100_100, goal_200_200, goal_paris.

    condgoal {$m_city.coord$==100,100} include goal_100_100
    condgoal {$m_city.coord$==200,200} include goal_200_200
    condgoal {$m_city.castle.name$==Paris} include goal_paris

    Set and Condgoal can be use quite effectively within snippets by experienced users. If you have multiple towns, chances are, the goals in the towns are quite similar. With condgoal, it is possible to modify the goals so that they become identical. In fact, you can even have all towns from multiple accounts sharing the same single goal.

    Please refer to the script section for all aspects of goal programming.


The script is written as some sort of assembly line language to send various commands to the server. Many state variables and functions within the bot are accessible to the scripts, allowing the scripts to send arbitrary commands to the server.

Here is a sample script:

attack 314,500 Bob,John,Max,Eve s:10 @3:00:02
attack 314,500 Bob,John,Max,Eve s:20 @3:00:02.3
attack 314,500 Bob,John,Max,Eve s:30 @3:00:02.6
attack 314,500 Bob,John,Max,Eve s:40 @3:00:02.9
Here is a more complex one:
// Attack a target with 4 waves using 4 heroes in 10 minutes. 
// The waves are scheduled to arrive 0.3 seconds apart

set target 314,500
setarr heroes "Bob John Max Eve"
set time $m_city.getLocalTime()$


set index 0
label start_waves
set hero %heroes[{%index%}]%
set index {%index%+1}

set desiredArrivalTime {%time%+10*60+0.3*%index%}
set troop s:{%index%*10}                // micro scout bombs :)
attack %target% %hero% %troop% @00:00:%desiredArrivalTime%

if {%index%<%heroes.length%} goto start_waves
To see a list of all script commands, run:
  listcommands filter
    Ex. listcommand trade
If filter is used, only commands containing the filter as a substring is listed. To find parameters needed for a particular command, type
  info command
    Ex. info attack
The state variables are undocumented. You can browse around with the inline command "\describe". You can start browsing with "\describe m_city", or "\describe m_city.cityManager". Be very careful with the functions provided in m_city.actionFactory as they may send communication with the server. "\describe" may have to call various functions in order to find out what you want it to describe, so it does more than just "describe". You can display the content of many internal state variables with command echo, for example "echo $m_city.castle.toDebugString()$" or "echo $m_city.cityManager.bestIdlePoliticsHero().toDebugString()$".

Be extremely careful with space. You are asking for trouble if you have space character(s) in the value of your variables.

Control Commands

  • sleep time: to pause the execution for some time
  • loop count label: to run a block of code a number of times
  • repeat count: to run a single line of code a number of times
  • goto label: to jump to a different line of code
  • if condition command args...: to execute a command depending on the condition
  • iferror expression command args...: to execute a command if given expression results in an error. For backward compatibility, certain command won't work with iferror, while "iferror expression label" still works as before.
  • gosub label params...: to call a subroutine and to suply the sub with parameters
  • gosubreturn value: to jump back to the place from which the subroutine was called with an optional return value.
  • echo message: to display message to the screen
  • include: Use "include snippet_name" to effectively copy and paste a named snippet from the Snippets tab.
  • setsilence: to control whether execution information is displayed
  • logout: disconnect the bot, pause the execution, and optionally schedule an execution resumption.
  • ifgoto: a conditional jump to a different line of code [obsolete]
  • ifgosub: a conditional subroutine call [obsolete]
  • print: to display information to the screen [obsolete]

    Use command "listcommands" to display all script commands and "info" to display more detail information about a command.

Special Commands

  • Interface commands for goals: A number of commands are available from command windows to set the goals, to ensure that goals are fully programmable. The commands are:
        resetgoals ...
        config ...
        buildinggoals ...
        techgoals ...
        troopgoal ...
        setballsused ...
    You most likely want to use these commands when you want to schedule the bot to work only for some period of time.
  • Troop movement commands
        deploy missionType coordinate hero troop [resource] [camptime]
        qdeploy missionType coordinate hero troop [resource] [camptime]
        attack coordinate hero troop [camptime]
        bigattack coordinate hero troop [camptime]
          bigattack consumes a war ensign!!!
        scout coordinate hero troop [camptime]
        reinforce coordinate hero troop [resource] [camptime]
        transport coordinate troop resource
        Ex. deploy attack 101,102 #best a:99995,wo:1,p:1,sw:1,s:1,warr:1 none @:15:20:10
        Ex. attack 101,102 any,!#absbest a:99995,wo:1,p:1,sw:1,s:1,warr:1
        Ex. bigattack 101,102 any s:125000
        Ex. scout 101,102 none s:100000
        Ex. (AgeII) colonize 101,102 #best a:20000,wo:1,p:1,sw:1,s:1,warr:1
        Ex. (AgeII) deploy colonize 101,102 #best a:20000,wo:1,p:1,sw:1,s:1,warr:1
        Use qdeploy instead of deploy when you want the command to fail 
          instead of to wait when the troops cannot be sent out 
          (no hero/troop/rally slot).
  • Build city: attack a flat and build a city there.
         buildcity coord
         Ex. buildcity xxx,yyy
    Do not use "deploy buildcity". As most of the towns you build are for npc, the default action for a new town is to npc it. To cancel buildcity, use
  • Building, research, troop, fortification
        create buildingType [location] [useHammer]
        create! buildingType [location] [useHammer]
          valid location is between 0 and 31 for inside buildings and 
            1001 to 1040 for outside building (sawmill, farm, ironmine, quarry)
          the default location is the first empty location
          Ex. create cottage
            to create a cottage
          Ex. create cottage 5
            to create a cottage at location 5 
          Ex. create cottage 5 true
            to queue a cottage at location 5 using a Bernini's hammer.
         upgrade buildingType [option] [useHammer]
         upgrade! buildingType [option] [useHammer]
          option is either "lowestlevel", "highestlevel", or "level1"..."level9".
          option "level9" must be used to upgrade level 9 building (and use mic script)
          Ex. upgrade cottage
          Ex. upgrade cottage level9
          Ex. upgrade cottage level9 true
         demo buildingType
         demo! buildingType
           Ex. demo inn
             to demolish inn by one level
           Ex. cancelbuild
             to cancel current building
         usebuilditem item
           Ex. usebuilditem Beginner_Guidelines
             to speed up current building
           Ex. waitnobuilding
             to wait for current building to complete
             do nothing if there is no current building
         research techType
           techType must be one of the technology or 
              "quickest", "slowest", "cheapest" or "dearest" (most expensive).
           Ex. research ag
             to research argriculture
           Ex. research quickest
           Ex. canceltech
             to cancel current research
         gear gearType
           Ex. gear weapon
             to upgrade weapon
         star gearType gem count
           Ex. star weapon delicate 4
             to attempt to upgrade weapon stars with 4 delicate gems.
             gem is either delicate or flawless (or their abreviations de/fl)
         autostar gearType targetLevel spec [spec]...
           each spec is of the form start:end:gem:count
           Ex. autostar weapon 9 0:6:de:4 7:15:fl:4
             to attempt to upgrade weapon stars to level 9 
             with 4 delicate gems when the star is from 0 to 6, 
             and with 4 flawless gems when the star is from 7 to 15.
           Ex. autostar weapon 9 0:2:de:2 3:5:de:4 6:6:fl:2 7:7:fl:3 8:15:fl:4
             to attempt to upgrade weapon stars to level 9 
             with 2 delicate gems when the star is from 0 to 2, 
             with 4 delicate gems when the star is from 3 to 5, 
             with 2 flawless gems when the star is 6,
             with 3 flawless gems when the star is 7,
             and with 4 flawless gems when the star is from 8 to 15.
         safestar gearType targetLevel [safetyFactor=2]
             lazy way to let the bot to upgrade the star by itself, attempting 
               to lessen the chance the star level is down by too much when star 
               upgrading fails. The higher the safetyFactor, the more conservative
               the star upgrading is.
             desirable when you wish to minimize your chance of ending up with
               a broken star set while upgrading star levels.
           Ex. safestar weapon 9
               safestar weapon 9 3
           Ex. safestar weapon 9 0
             upgrade star with absolutely no regard to recovery if fail
             essentially "autostar weapon 9 0:2:de:1 3:5:de:4 6:15:fl:4"
         usetechitem item
           Ex. usetechitem Beginner_Guidelines
             to speed up current research
           Ex. waitnoresearch
             to wait for current research to complete
             do nothing if there is no current research
         train troop [hero] [barrackList] [minAmount]
         train! troop [hero] [barrackList] [minAmount]
           Only one type of troop can be trained per command
           Ex. train a:1000
             to train 1000 archers
           Use train! version if you want to train troop immediately without waiting for town's turn.
         trainto troopLimit [hero] [barrackList] [minAmount]
           More than one type of troop can be specified, but only one type of 
           troop can be trained per command.  Do nothing if the troopLimit has
           been satisfied.  Cheap troops are trained first.
           Ex. trainto a:400000,s:200000
             to train toward having 400k archers and 200k scouts
           This is the script version of "troop" goal.
         untrain troop
           to untrain troops
           Ex. untrain a:1000,p:200
             to untrain 1000 archers and 200 pikemen.
           Ex. untrain sw:-1000,p:-200
             to untrain swordmen and pikemen to have exactly 1000 swordmen and 200 pkemen left.
         clearbarrackqueues [remain_count]
           Ex. clearbarrackqueues
             If clear queues except the first batch in all barracks
           Ex. clearbarrackqueues 2
             If clear queues except the first 2 batches in all barracks
         clearqueuetype trooptype
           Ex. clearqueuetype a
             remove all archers in the queue
         walldefense fortType number [buildType]
         walldefense! fortType number [buildType]
           Ex. walldefense at 1000
             To build 1000 archer towers
           Ex. walldefense at 10000 demo
             To remove 10000 archer towers
           Use walldefense! if you want to queue defense immediately without waiting for town's turn.
         walldefenseto fortLimit
           More than one type of fortification can be specified, but only one type of 
           fortification can be built per command.  Do nothing done if the fortLimit has
           been satisfied.  Cheap fortifications are built first.
           Ex. walldefense trap:10000,ab:10000
           This is the script version of the "fortification" goal.
         clearwallqueue remain_count
           Ex. clearwallqueue
             To cancel fortifications queue, leaving only the first batch left
           Ex. clearwallqueue 3
             To cancel fortifications queue, leaving only the first 2 batches left
  • Trading:
         buy resource amount price
           Ex. buy lumber 1000000 1.34
             to buy 1m lumber at 1.34
             You can see the current bidding/asking price in the resource tab
         sell resource amount price
           Ex. sell lumber 1000000 1.34
             to sell 1m lumber at 1.34
             You can see the current bidding/asking price in the resource tab
         buyto resource limitAmount price [goldReserved]
           Ex. buyto lumber 10000000 1.34
             to buy lumber at price 1.34 toward having 10m lumber
             if there are already 10m or more lumber, do nothing
           Ex. buyto lumber 10000000 1.34 10000
             to buy lumber at price 1.34 toward having 10m lumber, leaving a minimum of 10k gold left
             if there are already 10m or more lumber or less than 10k gold, do nothing
         sellto resource limitAmount price [goldReserved]
           Ex. sellto lumber 1000000 1.34
             to sell all lumber except 1m at 1.34
             if there are less than 1m lumber, do nothing.
           Ex. sellto lumber 1000000 1.34 10000
             to sell all lumber except 1m at 1.34 or to have 10k gold
             if there are less than 1m lumber and more than 10k gold, do nothing.
           Ex. canceltrade
             To cancel all pending trades
         usetradeitem item [tradeId]
           To speed up transaction.  The tradeId is found in the exchange (X) tab. 
           If tradeId is obmitted, the first transaction would be sped up.
           Ex. usetradeitem Merchant_Fleet 2642735
             To speed up the shipping of trade with id 2642735
  • Gate control:
         When "gate" config is off, the gate can be controlled via script command setgate.
         setgate state
           Ex. setgate true
             to open the gate
           Ex. setgate false
             to close the gate
         When "gate" config is on, the gate setting can be done via the goal line "gatepolicy".  "gatepolicy" can also be set via script.
  • Guarded attack: schedule a scout and an attack and recall the attack based on the result of the scout.
         guardedattack location troop num_scouts opponent_troop [opponent_fortification]
         Ex. guardedattack 100,101 a:99600,warr:100,s:100,p:100,sw:100 10 a:60000,cav:50000
         Ex. guardedattack 100,101 a:99600,warr:100,s:100,p:100,sw:100 10 cav:-80000 trap:-1
         Ex. guardedattack 100,101 cav:99000,s:1000 10 p:100000 trap:1,ab:1
    In the first example, the bot will schedule a scout with 10 scouts and an attack on 101,101 with 99600 archers so that the scouts arrive a random time between 15-30 seconds before the archers. If the scouting fails, the attack is recalled. If the scout is successful but there are 60+k archers OR 50+k cavalries at the target, the attack is also recalled.

    In the second example, the intention is to kill your opponent cavalries. The bot recalls troops when the scouting fails or when there are *strictly* less than 80k calvaries (i.e. 79999 cavaries or less) in the town or when there is strictly less than 1 trap (i.e. no trap).

    The 3rd example is a guard for cavalry smack. The bot recalls troop when the scout fails or when there are either trap or abatis or 100k pike.

    Guarded attack is simply a combination of other commands. If you want more control over the details of the attack, you can manually schedule attacks and scouts and use "setguard" to monitor the attack. "setguard" is also useful if you have to restart the bot.

         setguard location opponent_troop
            attack 100,101 any w:10000,a:100,s:100,p:100,sw:100 @:14:00:00
            attack 100,101 any a:99600,warr:100,s:100,p:100,sw:100 @:14:00:02
            sleep 0:15:00
            deploy scout 100,101 any s:100000 none @:13:59:40
            setguard 100,101 a:60000,cav:50000 trap:10
    You can cancel guarded attacks with
    By default, the bot waits a short time before canceling the attack to be more human like. You can change this waiting time with "config response:min", for example "config response:8". The default delay is randomly set between 7 and 15 seconds.
  • Loyalty attack: repeatedly send waves of cavalry to a target, on failure, recall all waves (including loyalty attack waves sent from other towns). Heroes sent on loyalty attack missions are made sure to be at 100 loyalty.
         loyaltyattack target num_cavalry
         Ex. loyaltyattack 100,101 3000
         capture target num_cavalry
         Ex. capture 100,101 3000
    You can cancel loyalty/capture attacks with
    The main different between "loyaltyattack" and "capture" is the time when the attack ends. For "capture", the waves end when the town is captured, and for "loyaltyattack", the waves end when the loyalty of the town is down to 7. In general, the command "capture" is good when all the defenses are down. The command "loyaltyattack" is useful in case the opponent leaves the gate closed with troops inside. Once the waves end, a final attack is normally required to capture the town. It is also possible to run "capture" from one town, and "loyaltyattack" from another. The heroes used in loyalty attacks can be specified using the *goal* line "spamheroes hero1,hero2..."

    You can modify the response time with "config response:min" as in loyalty attack.

  • Spam attack: repeatedly attack a town. Heroes are made sure to be at loyalty 100 before sending out unless "notspamheroes" are set.
         spamattack target troop num_waves
         Ex. spamattack 100,101 warr:400,a:1,p:1,sw:1 10 
    You can cancel spam attacks, send the spamattack command again with 0 as num_waves. The feature is useful for clearing traps or abatis. The heroes used in spamattack can be specified by setting *goal* "spamheroes hero1,hero2,..." or by setting "notspamheroes hero1,hero2,...".

    You can modify the response time with "config response:min" as in loyalty attack.

    Your hero may be captured even if his/her loyalty is 100.

  • Honor attack: Similar to spam attack, but the termination condition is a negative honor in the attack.
         honorattack target troop [honor_condition]
         Ex. honorattack 100,101 warr:100
           attack and stop if honor is lost
         Ex. honorattack 100,101 warr:100 100000
           attack and stop if honor lost is more than 100000
         Ex. honorattack 100,101 warr:100 -100000
           attack and stop if honor gain is more than 100000
    The command is useful for taking out traps and abatis of enemy towns or for the negative honor condition, to dump honor.

    You can modify the response time with "config response:min" as in loyalty attack.

    Your hero may be captured even if his/her loyalty is 100. When using honor attack, it is recommended that you use config line "notspamheroes" to specify the heroes you don't want to use, and have "fasthero" enabled to hire new heroes when current ones are captured.

  • Valley war:Valley war is nasty. It is a waste of time to defense valleys in general, especially when most of the time your heroes are out farming. It is easier to retaliate with:
         fieldattack alliances coord radius minlevel
         Ex. fieldattack Storm,Storm2 101,102 100 7
           to attack all valleys level 7 or above within 100 miles of 101,102
           owned by alliance Storm or Storm2.
    You will need scouts for the attacks. As hero can be easily lost when attacking valleys, it's best that you have a town dedicated for this valley war (say a newly captured npc 10). For efficiency, use "config hero:10,fasthero:10" to enable hiring hero for replacement, and goal line "notspamheroes none" to specify that all heroes can be lost.

    A bot could easily clear out valleys in an entire state within a day.

    You can cancel field attack with "endfieldattack".

  • Evacuate town: Useful when you want to move all your troops out to another town before running "abandontown". If you have a lot of resource in the town, make sure the town have many transports. The bot will move most troops and resource to another town. Note that the heroes are not moved automatically.
         evacuatetown coord [troop_only_flag]
         Ex. evacuatetown 101,102
           to send all troops and resources to 101,102
         Ex. evacuatetown 101,102 true
           to send only troops to 101,102
    You can cancel evacuation with "endevacuate".
  • Troop recall: To recall troops, use either "recall", "herorecall" or "idrecall". Recall is used to recall all troops heading to a destination. "herorecall" is used to recall troops lead by a particular hero. idrecall is used to recall a specific army.
         recall location
         Ex. recall 100,101
         herorecall heroName
         Ex. herorecall Ryan
         idrecall armyid
         Ex. idrecall 1089052
    The id of your own army can be found in the army tab, and the id of friendly army is in the extra troops tab.
  • Troop healing: The bot heal your injured troop on its own by default. There are time when you want them to be healed manually, for example, in between the attacking waves at your town.
            sleep @:14:01:32
    Healtroops will not heal your troop if the bot has no information on injured troop. If you want to force the bot to send a heal command to the server, use "healtroops2" instead. This is desirable, for example, when you have just captured a town. If you wish the bot not to heal your troops automatically, use "config nohealing:1".
  • Travel info: find the attack travel time or reinforcement travel time, as well as food usage and carrying load.
         travelinfo coord troop
         Ex. traveltime 102,100 cav:10,cata:10
  • Wartown: If you wish to temporarily disable all troops movement, you can use "config wartown:1". The bot won't send out npc farming or valley capturing waves. You can additionally set the time for this war town condition with "wartownpolicy start_time stop_time", for example "wartownpolicy 20:00 22:00". Multiple starting and stopping times are also possible, for example "wartownpolicy 11:00 12:00 20:00 22:00".
  • Miscellaneous: Other commands that may be useful
         Ex. listmedals
           to list all medals
         listitems [filter]
           to list all items, including medals
           Ex. listitems
           Ex. listitems guides
             to list all items containing "guides"
         useitem itemname
           to use an item (not all items can be used with this command)
           Ex. useitem Ivory_Horn
         buytem itemname [count]
           to buy an item, or count items if count is specified
           Ex. useitem Ivory_Horn
           Ex. useitem Ivory_Horn 3
         useheroitem hero itemname
           to use an item on a hero
           Ex. useheroitem SuperHero Excalibur
         usestratitem target strategyItemName
           Age II only, to cast a strategy item on a location
           Ex. usestratitem 100,101 Burn_the_Warehouses
           Note: error message for this command may be written in Chinese!!!
         usearmyitem armyId armyItemName
           Age II only, to cast a strategy item on your own army
           Ex. usearmyitem 10023521 Cover_up_Army_Maneuvers
           The armyId can be found in the pop up text in the army tab
           Note: error message for this command may be written in Chinese!!!
         awardgold hero
           to increase hero's loyalty by 5
           Ex. awardgold Bob
         uplevelhero hero
           to increase hero's level by 1
           Ex. uplevevelhero Bob
         addpointhero hero pol atk int
           to allocate unassigned points (from upleveling) to politics/attack/intel.
           Ex. addpointhero Bob 0 2 0
         persuadehero heroname
           Ex. persuadehero Bob
           to persuade a captured hero Bob
           the medals required for the persuasion if any are shown in hero tab.
         firehero heroname
           Ex. firehero Bob
           to fire a hero from the feasting hall. The hero status must be either
           idle, mayor, or captured, i.e. is not on a mission away from town.
           Ex. getspamhero
           to get the best attack hero currently available in the inn
           this is best when the inn has high level
           To obtain politics hero, use "getspamhero management" 
           To obtain intel hero, use "getspamhero strategem"
         dumpresource coord condition resource
           Ex. dumpresource 101,100 f:1000000,g:500000 f:500000,g:250000
           to dump resource to another location when there are too much resource
           transporters are needed
           Ex. dumptroop 101,100 a:100000,s:500000 a:200000,s:150000
           to dump troops to another location when there are too many troops
         excercise troops troops
           Ex. excercise a:99000,p:2000,sw:2000,cav:2000,cata:2000,warr:2000 a:100000
           to run the combat excercise between two groups of troops
           Ex. hiderainbow
           to send the rainbow away
           should work only when the town is under attack
           The rainbow are often sent out automatically when the gate is open,
             but if you wish to hide your resource before the gate change time, 
             (i.e. the value for hiding config is larger than gate config"),
             you may have to send out the rainbow manually.
           You can change the time the rainbow to be back with 
             "config attackgap:sec", for example "config attackgap:30". The rainbow
             will be scheduled to return if there is no attack in that period.
           Ex. listbuffs
           to buffs active at login time
         attackwait type
           Ex. attackwait loyalty
           Ex. attackwait honor
           Ex. attackwait spam
           to wait for loyaltyattack, honorattack, or spamattack to end
           Ex. waitresource f:10000,w:3000,i:2000
           to pause the script execution until the resources listed are available.
           Ex. waithero super_hero
           to pause the script execution until hero "super_hero" is available
           Ex. waitherolost hero1,hero2,...
           to pause the script execution until one of the heroes specified is captured
         teleport state
           Ex. teleport Lower Lorraine
           Ex. teleport bohemia
           Goal must be set again manually after using teleport!!!
         advteleport location
         warteleport location
           Ex. advteleport 100,100
           Ex. warteleport 100,100
           Experimental feature
           Force the goal section of the the bot to execute *once* on towns not in 
           their natural order, on buildnpc task or on all tasks expectively.
         vote (Age II only)
           Ex. vote Bob
           to vote for a player
  • Map search: The search is done in two stages. In the first stage you ask the bot to cache map information and in the second stage, query from the cache what you want. To cache map information, use one of the following commands:
         scanmap location radius
         Ex. scanmap 101,100 30
         scanrec nw_corner se_corner
         Ex. scanrec 125,250 250,375
    Note that the map near your towns are used by the bot and are cached by default. To update areas that were previously scanned, use:
         rescanmap location radius
         Ex. rescanmap 101,100 30
         rescanrec nw_corner se_corner
         Ex. rescanrec 125,250 250,375
    You can scan the fields to find who owns what around you with:
         scandetail location radius
         Ex. scandetail 101,100 6
    To look up map information, you can use one of the following inline commands. Inline commands start with character "\" and must be typed in the the chat line.
         \searchenemies [maxtowns]
         Ex. \searchenemies
         Ex. \searchenemies 1000
         \searchcastle alliance|cityname|nickname
         Ex. \searchcastle Defiance
         Ex. \searchcastle BobVille
         Ex. \searchcastle Bob
         \searchsuzerain nickname
         Ex. \searchsuzerain Bob
            to find towns suzerained by Bob
         Ex. \searchsuzerain none
            to find towns not suzerained by anyone
         \listcastles NWcorner SEcorner [maxtowns]
         Ex. \listcastles 100,110 240,260
         Ex. \listcastles 100,110 140,260 100
         \searchfields alliance|nickname
         Ex. \searchfields Defiance
         Ex. \searchcastle Bob
    You can also use
         \loc location
         Ex. \loc 101,100
  • FindField: List locations of interest You can use findfield command to search the known map.
         findfield fieldtype fieldlevel distance
         Ex. findfield NPC 5 6
           to list for all NPC level 5 within 6 miles
    The field type is one of the following Forest, Desert, Hill, Swamp, GrassLand, Lake, Flat, NPC.
    You can optionally specify hero, troop, and center coordinate for findfield.
         findfield fieldtype fieldlevel distance hero troop [center]
         Ex. findfield NPC 5 6 any b:400,t:400
           to get a farming script
         Ex. findfield NPC 5 6 any b:400,t:400 101,102
           the get a farming script for npc 5 within 6 miles of 101,102
         changecastlename new_castle_name
         Ex. changecastlename BobVille
           to change the castle name to BobVille
         changeflag new_flag
         Ex. changeflag BOTT
           to change the flag to BOTT
  • Monitoring: Monitoring your opponents to find out public changes. If a nick contains space character, it must be replaced with "-".
         monitorprestige nick [population_flag]
         Ex. monitorprestige Bob
           To alert you when the prestige of Bob changes
         Ex. monitorprestige Long-Name
           To alert you when the prestige of "Long Name" changes
           Space in name must be replaced by character -
         Ex. monitorprestige Bob true
           To alert you when the prestige or population of Bob changes
  • Colony: This command is specific for Age II, to manage colonies
         colony operation target [troop]
           where operation is either "abandon", "food", "army", "population",
             "disarm", "overview", "sowdiscord", "infoarmy", "suppress"
           to abandon colony, levy food, draft army, redeploy population,
             disarm army, overview colony, sow discord, view colony army info
         Ex. colony overview 100,102
           to view the status of the colony
         Ex. colony army 100,102
           to draft troops from the colony
         Ex. colony suppress 100,102
           to view suppression setting for 100,102
         Ex. colony suppress 100,102 a:100,warr:10,p:10,sw:10,wo:10
           to set suppression troops for 100,102 to 100% archer, 10% warrior,
             10% pike, 10% swords, 10% worker
           be careful with setting suppression troop, as you can only change
             the suppression setting once every 5 hours.
  • Capital policy: This command is specific for Age II, and should work only in the Historical City you own.
         capitalpolicy operation target
           where operation is either "food", "army", "population",
             "disarm", "tax"
           to levy food, draft army, redeploy population,
             disarm army, or to tax the target
         Ex. capitalpolicy army 100,102
           to draft troop from 100,102
  • Change hero gear: This command is specific for Age II.
         changeherogear hero gearType
           where gearType is either "none", "pol", "atk", or "int"
         Ex. changeherogear Queen atk
           to change all gears of hero Queen to attack gears.
  • completequests:
         completequests type
           where type is either daily or routine or [AgeII only] donate
         Ex. completequests daily
         [AgeII] donatequest questId
           to make the donation needed for a quest
           questId must be one of the numbers displayed by "completequests donate"
  • Other inline commands:
         \who nickname
         Ex. \who Bob
         \alliance alliancename
         Ex. \alliance Storm
         \listmail page
         Ex. \listmail 2
           to show mails, 2nd page
         Ex. \listsentmail 3
           to show mails sent, 3rd page
         Ex. \listsystemmail 2
           to show system mails, 2nd page
         \mail receiver topic message
         Ex. \mail Bob our_meeting see you at 3:00PM server time
         Ex. \members
           to list members in your alliance
         \warreport page
         Ex. \warreport 3
           to show page 3 of the war reports
         \armyreport page
         Ex. \armyreport 1
           to show page 1 of your army reports
           report URLs are obtained automatically
         \quickarmyreport page
         Ex. \quickarmyreport 2
           to show page 2 of your army reports
           report headlines are shown together with report id
         \readreport reportid
         Ex. \readreport 91706
           to show report URL for report 91706
           report id are provided by \quickarmyreport
         \apply alliance
         Ex. \apply Defiant
           to apply to alliance Defiant
         \accept nick
         Ex. \accept Bob
           to accept Bob into the alliance
           necessary privilege required
         \invite nick
         Ex. \invite Bob
           to invite Bob into the alliance
           necessary privilege required
         \join alliance
         Ex. \join Defiant
           to join alliance Defiant
           invitation from alliance is needed before joining
         \eject nick
         Ex. \eject Bob
           to kick Bob out of the alliance
           necessary privilege required
         \setenemy alliance
         \setneutral alliance
         \setfriend alliance
         Ex. \setfriend Storm
           to set alliance Storm to be friendly
         \sethost nick
         \setvicehost nick
         \setpresbyter nick
         \setofficer nick
         Ex. \setofficer Bob
           to set Bob an officer
           necessary privilege required
         \qattack target hero troop [camptime]
         \qscout target hero troop [camptime]
         \qtransport target troop resource [camptime]
         \qreinforce target hero troop resource [camptime]
           Inline version of script commands attack, scout, transport, reinforce. Useful when the script is running some other scripts.
         Ex. \qscout 100,101 none s:1
           to scout 100,101 with 1 scout and no hero.
         \qcapitalpolicy operation target
         Ex. \qcapitalpolicy army 100,101
           to draft troop from the town at 100,101
           see capitalpolicy script command
         \qcolony operation target [troop]
         Ex. \qcolony army 100,101
           to draft troop from the colony at 100,101
           see colony script command
  • "Calibrate" command and notes on camp time There are 3 different ways to specify the camp time value for troop movement commands (attack, reinforce, transport, colonize, deploy). The standard way is just a delay time, for example "attack xxx,yyy any s:100000 3:00". In this example, the 3 minutes delay is sent straight to the server. The 2nd way is to specify the desired arrival time with @ character, for example "attack xxx,yyy any s:100000 @:10:00:00". The bot will compute the delay time appropriately to send to the server. It is strongly recommended that you run "calibrate" to improve the accuracy of the timing. The 3rd way is only making sense when you coordinate attacking waves from one or more towns (and in a loop). The delay time is relative to a common time marked with command "calibrate" using the "+" character. Here is an example:
       label start
       waithero JUNKHERO
       attack xxx,yyy JUNKHERO s:10000 +3:00.0
       attack xxx,yyy any cav:10000 +3:00.5
       repeat 5
       goto start
    If the command calibrate is executed at 10:00:00, the next commands schedule one wave arriving at 10:30:00.0 and 5 waves arriving at 10:30:00.5.

    As a note, better estimate of attack arrival time comes at a cost: poorer estimate of enemy arriving time. This is unfortunately a problem, because the asymmetric nature of the network communication between the bot and the server.

  • Debug The bot can display more details information on what it does if you set the config debug. The most basic information are shown with "config debug:1". For certain tasks, you can get more information. Use "config debug:10" to see messages about troop training, "config debug:11" for npc farming, "config debug:12" for war report, "config trading:13" for trading.

    If you try to get the bot to do something and fail, you may want to try to find out more information about what is going on. Telling others that you fail simply means just that, you fail. If you want to know what you can do differently to get the bot to do what you want, please make sure to set the appropriate value for debug to see what the bot says when it doesn't do what you want it to do.