Citavon Bot

-autoscriptsConfig¶

Usage

-autoscripts <1|0>

Example

-autoscripts 1

Values

1 (or yes, on, true): autorun on. 0 (or no, off, false): off. Anything else is refused.

Default

Off.

See also

-runscript, AutoRunScript.txt

Switches on autorun: scripts that start by themselves. After the console's first login (never after a reconnect), every city runs, one after the other:

1. the start-up file: the -runscript file if you set one, otherwise AutoRunScript.txt from your scripts folder if it is there;
2. then each of the city's loadouts that holds the line label autorun, Load 1 first, each from that label down.

The cities run side by side. When one script ends, that city's next one starts. If you stop one, the rest of that city's autorun does not start. A city where a script is already running is skipped.

To stop a crash loop from sending the same orders again and again, autorun starts at most once every 10 minutes for a lord. A console that restarts sooner logs "not started — it already started N minute(s) ago" and skips it.

With autorun off, the Log says so once after logging in. With it on but nothing to run, the Log says that too.

-runscriptConfig¶

Usage

-runscript <file>

Example

-runscript "morning chores.txt"

Values

A file name inside your scripts folder. A name that points outside the folder is refused.

Default

AutoRunScript.txt

See also

-autoscripts

The file every city runs first when autorun starts. It only matters with -autoscripts 1. If the file you name is not there, the Log says so and the cities go on to their label autorun loadouts. If you don't set it and there is no AutoRunScript.txt, nothing is said: only the loadouts run.

-autorunConfig¶

Usage

-autorun <0|1>

Example

-autorun 0

Values

0 (or no, off, false): the engine starts paused. 1 (or yes, on, true): no effect. Anything else is refused.

Default

Not set: the engine starts the way you left it.

Controls the goals, not the scripts. With -autorun 0 the console starts with its engine paused, so no goal acts until you press ❚❚ in the console to resume. Scripts and autorun still run.

Without it (or with 1), the engine starts as it was: a lord you paused stays paused after a restart, a running one runs. -autorun 1 does not resume a paused lord.

-maxtradeConfig¶

Usage

-maxtrade <amount>

Example

-maxtrade 5000000

Values

A whole number, at least 1, written out in full (no k or m).

Default

Not set: the bot puts no cap on an order.

See also

buy, sell

The most one market order placed by a script's buy or sell (or the same typed as an in-line command) may be for. A bigger order is not sent: the script's Output says "not sent — more than one order may be for (-maxtrade …)" and the script carries on. A guard against a typo selling your whole stock. Orders from the trade goals and the console's Market tab are not checked.

-teleportConfig¶

Usage

-teleport <state | random>

Example

-teleport random

Values

One of the map's states by name (in quotes if it has a space), or random.

Default

Not set.

See also

autoteleport

The state autoteleport moves cities to when the script line names none. Scripts can also read it as Config.teleport. A name that is not a state is only noticed when autoteleport runs, which then refuses with the list of states.

-autologinConfig¶

Usage

-autologin <value>

Default

Not set.

Accepted and kept, but does nothing: a console always logs in. To keep a lord out of the game, switch it off in the Director (untick On).

-titleConfig¶

Usage

-title <text>

Default

Not set.

Accepted and kept, but does nothing: a console's browser tab is always named after the lord's label. Change the label in the Accounts grid instead.

-usernameConfig¶

Usage

-username <name>, also -u

Refused. The lord logs in with its own Lord name from the Director. Change that in the Accounts grid or the ✎ dialog.

-passwordConfig¶

Usage

-password <password>

Refused. The lord's stored password is used. A password in a start-up parameter would be visible to anyone on the computer who looks at running programs.

-serverConfig¶

Usage

-server <address>, also -s

Refused. The game's address is set once for the whole fleet in the Director's Settings.

-proxyConfig¶

Usage

-proxy <address>

Refused. Citavon Bot always connects straight to the game.

-prependgoalsConfig¶

Usage

-prependgoals <file>

Refused. Write the goals into the lord's Prepend text in its console (Goals → the selector → Prepend): they run before every city's own goals.

-appendgoalsConfig¶

Usage

-appendgoals <file>

Refused. Use the lord's Append text in its console: it runs after every city's own goals.

configGoal¶

Usage

config <key>:<value>[,<key>:<value>…]

Example

config comfort:1,hero:1,troopsusereserved:0.25

See also

config (script), Prepend and Append

Sets one or more switches for the city. Pairs are separated by commas and written with no spaces: key:value. A pair with a space in it is an error and is skipped; the other pairs on the line still count.

A city may have as many config lines as you like. They are merged, and when the same key is set twice the last one wins, also across Prepend, the city's own text and Append (Append wins). A key with a bad value is an error; for the troop and wall settings the key then keeps its default rather than a value that could mean something else. An unknown key turns the line red and does nothing.

A key written as a line of its own (comfort 0, itemspeedup 0) is read as config comfort:0, and the note under the editor says so. In a script, config key:value adds the setting to the city's running goals until the goals are reset.

config buildingConfig¶

Usage

config building:<0|1>

Example

config building:0

Values

0 the builder is paused; 1 it works.

Default

1 (any build line is enough)

See also

build, plan

With building:0 the city starts no building job of any kind: not the build lines, not the plan lines' buildings, not the buildings research needs, not the Walls a fortification goal needs. A job already under way finishes. The Engine view says "paused by config building:0". Any other value than 0 or 1 is an error.

config researchConfig¶

Usage

config research:<0|1>

Example

config research:0

Values

0 research paused; 1 on.

Default

1

See also

research

With research:0 the city starts no research, and the builder no longer raises the buildings that research lines need. A research already under way finishes.

config planConfig¶

Usage

config plan:<0|1>

Example

config plan:0

Values

0 plan lines are ignored; 1 on.

Default

1

See also

plan

With plan:0 every plan line is left out, as if it were not there. Ordinary build and research lines still run.

config troopConfig¶

Usage

config troop:<0|1>

Example

config troop:0

Values

0 no troop training; anything else, on.

Default

on

See also

troop

With troop:0 the city queues no troops for its troop lines ("troops: off (config troop:0)"). Batches already queued carry on. The training hero still judges the city's troop stages when it chooses where to go next.

config fortificationConfig¶

Usage

config fortification:<0|1>

Example

config fortification:0

Values

0 no fortifications are built; 1 on.

Default

1

See also

fortification

With fortification:0 no fortification batches are queued, and a city with no Walls no longer has the Walls built for its fortification lines.

config freespeedupConfig¶

Usage

config freespeedup:<0|1>

Example

config freespeedup:0

Values

0 off; anything else on.

Default

on

See also

itemspeedup, Speed-ups and the builder

Citavon finishes a building or research job for free when the job is short enough (5 minutes or less; the game decides which jobs qualify). The bot uses this the moment such a job starts: it is the first thing in every pass, once per job, for the building job and the research job of each city. It costs nothing. Troop and wall batches never qualify (Citavon only speeds those up with items).

Turn it off only if you want short jobs to run their course, for instance to watch a city by hand.

config itemspeedupConfig¶

Usage

config itemspeedup:<0|1>

Example

config itemspeedup:0

Values

0 off; 1 on. Anything else is an error.

Default

1 (on)

See also

freespeedup

Finishes a building upgrade with speed-up items the account already holds, when the free speed-up does not cover it. The bot picks the cheapest set of items, by their shop price, whose time covers what is left of the job; among equal prices, the fewest items, then the least time wasted. The items it may use are the fixed-time ones: Speed-up 15 min, Speed-up 1 hour, Speed-up 2.5 hours, Speed-up 8 hours, and Speed-up 10-30 hours (counted as 10 hours).

What it never does:

• buy anything: only items you hold are used;
• use the items that cut a share of the time (Builder's Ledger, Stonecutter's Masterwork) or the troop and wall ones (Drillmaster's Diary, Engineer's Notes);
• speed up research, troops, walls or a building being taken down;
• act on a job with 5 minutes or less to go, or one longer than 4 days;
• use part of a set: if the items you hold cannot finish the whole job, it waits (and tries again if you get more items while the job runs).

Each job is tried once. Using the items takes one action each, out of the pass's 6; if there are not enough actions left the job waits for the next pass.

config comfortConfig¶

Usage

config comfort:<0|1>

Example

config comfort:0

Values

0 off; 1 on. Anything else is an error.

Default

1 (on)

See also

comfortpolicy, taxpolicy

Keeps the city's loyalty up and public grievance down with the Town Hall's comfort actions, and runs the tax (taxpolicy). With comfort:0 the bot leaves comfort, levies and the tax rate alone.

At most one comfort action a pass, and the bot tries each kind (relief, prayer, each levy) at most once every 15 minutes, as Citavon allows. What it does, in order:

1. Riot risk first. The bot treats a city as at risk when its loyalty is under 30, its public grievance is 50 or more, or its loyalty is drifting toward a value under 30 (loyalty heads for 100 minus the tax rate minus the grievance). Then: it gives disaster relief when grievance is 50 or more (or there is any grievance and loyalty is under 30) and the city holds at least its population limit in food; it prays once loyalty is within 10 of the line (under 40) if the city holds at least its population limit in gold; and the tax drops to the lowest your taxpolicy allows. If it cannot afford prayer, the Engine view says "RIOT RISK" and how much gold it needs.
2. Ordinary comfort. Disaster relief whenever there is any grievance and the city has over 1,000,000 food; prayer whenever loyalty is under 95 and the city has over 100,000 gold.
3. Your comfortpolicy, if there is one (see below).

comfortpolicyGoal¶

Usage

comfortpolicy <min_minutes> <max_minutes> <option>[,<option>…]

Example

comfortpolicy 30 60 popraise,bless

comfortpolicy 15 15 gold

Values

Option	Short	What it does
popraise	po	Raise population. Skipped when the city is at its population limit.
bless	bl	Blessing (on Citavon it spares the city its next riot).
pray	pr	Prayer.
relief	dr	Disaster relief.
gold, food, wood, stone, iron	go fo wo (lu) st ir	A levy of that resource. Skipped while loyalty is under 80 (a levy costs loyalty).

See also

comfort

Every min to max minutes (a random time in between), the bot does the first option in your list that can be done now, then waits again. If none can be done, it tries again on the next pass. Options may be separated by commas or spaces.

It needs config comfort on, and it comes after the riot-risk and ordinary comfort steps: in a pass where those acted, the policy waits. Each kind still has its own 15-minute timer. One line per city; a second line replaces the first.

taxpolicyGoal¶

Usage

taxpolicy <min_rate> <max_rate> [<war_rate>]

Example

taxpolicy 10 30

taxpolicy 5 40 60

Values

Whole percentages from 0 to 100; min may not be above max. war_rate: the rate while an attack is on its way to this city.

Default

without a line: 0 to 100, no war rate

The bot keeps the tax as low as it can within the range: the lowest rate whose gold income covers the city's hero salaries, but never under min or over max. When the city holds gold for a week of salaries (and at least 1,000,000), it goes to min. A city at riot risk (see comfort) also goes to min.

With a war_rate, while an attack is on its way to the city the tax is set to it, whatever else is true. It goes back once the attack has landed or turned away.

Needs config comfort on. One line per city.

productionGoal¶

Usage

production <food> <wood> <stone> <iron>

Example

production 100 100 100 100

production 100 50 50 100

Values

Four whole percentages, 0 to 100: the share of each resource's fields that is worked.

Holds the city's field work at these shares. When one differs, the bot sets it, one resource per pass. Fewer workers in the fields leaves more idle population for training. It does not depend on config comfort. One line per city.

troopsusepopmax lowers these shares for a moment to free workers for a troop batch and puts them back straight after.

warehousepolicyGoal¶

Usage

warehousepolicy <food%> <lumber%> <stone%> <iron%>

Example

warehousepolicy 40 20 20 20

Values

Four whole percentages; together at most 100.

Holds the city's Warehouse split: the share of the warehouses' protected space given to each resource (the part an attacker cannot carry off). When the city's split differs, the bot sets it. Gold is never protected by warehouses. One line per city.

schedulepolicyGoal¶

Usage

schedulepolicy <start> <end> [<start> <end> …]

Example

schedulepolicy 06:00 12:00 18:00 23:30

schedulepolicy 22:00 06:00

Values

Times as hh:mm, 24-hour (24:00 allowed as an end), in start/end pairs. A window may run past midnight.

Default

no line: always

The city's goals act only inside these windows. Outside them only the city's defence runs (War Town Mode, hiding, the gate, defensepolicy, warrules, the Embassy and healing), plus the free speed-ups and item finishes, which come first in a pass. Nothing that keeps a city safe waits for the schedule. Quests are still claimed.

The times are the clock of the computer the bot runs on, not the game's clock. The Engine view says "outside 06:00-12:00, 18:00-23:30 — only the defence runs". One line per city.

processingpolicyGoal¶

Usage

processingpolicy [/start:<hh:mm>] [/end:<hh:mm>] <task>[:<priority>] …

Example

processingpolicy n:10 !b *:5

processingpolicy /start:22:00 /end:06:00 !n

Values

Task	Marches it covers
n	NPC farming
b	buildnpc (founding cities on flats)
v	valley farming
s	safe valley farming (its scouting)
a	valley and flat taking
m	medal hunting
t	troop sends (sendtroops, requesttroops) and the training hero's moves
r	resource sends (sendresources, requestresources)
q	rescue: accepted, nothing uses it

Turn a task off with !x, x:0 or x:off. !* turns off every task the line does not name; *:N gives the rest priority N. = may stand for :. A task named without a number gets 10. /start and /end (hh:mm or hhmm) make the line hold only between those times; the window may run past midnight.

Default

every task on

See also

rallypolicy

Before a goal sends a march, the bot asks whether its task is allowed. A march whose task is off is not sent, and the goal's note in the Engine view ends "held: processingpolicy: npc farming is off". Marches you send yourself, or a script sends, are never held.

You may write several lines. Lines without times are read first, then the timed lines whose window is open now; for each task the last line that mentions it wins (a line with *:N or !* mentions every task). So the example above turns NPC farming off at night only.

Priorities are read and shown but do not change the order in which goals run: the engine always works through its steps in the same order, and a pass sends few marches. Only "off" changes anything. A transfer from another city answers to the sending city's policy.

rallypolicyGoal¶

Usage

rallypolicy <kind>:<slots> [n:<level>:<slots>] … [max:<slots>]

Example

rallypolicy n:8 n:10:1 r:2 t:1 max:8

Values

Kinds as in processingpolicy: n b v s a m t r (also npc, buildnpc, valley, safe, acquire, medal, troop, resource, transport…), plus: n:<level>:<slots> a limit for NPC runs to one camp level (n:*:8 is the same as n:8); max:<slots> goals start nothing once that many marches of the city are out, whoever sent them. The older form /npc:3 also works.

Default

no limits beyond a full Rally Spot

Limits how many of the city's Rally Spot slots each kind of goal march may hold at once. A march holds its slot while it goes, camps and comes back. Marches staying in another city as reinforcements do not count toward these limits. A march a goal sent counts by the kind it was sent for; one you or a script sent counts by its mission: attack as n, transport as r, reinforce as t, build as b, scout as s.

It only ever lowers what goals may send. It keeps nothing free for you: for that, set max below the Rally Spot's slots. With or without the policy, no goal march goes when the Rally Spot is full. One line per city.

config completequestsConfig¶

Usage

config completequests:<0-3>

Example

config completequests:1

Values

Value	What is claimed
0	Nothing.
1	Every finished quest and the daily gift; no promotions.
2	All of 1, and promotions (rank, then title) as they come.
3	All of 1, and promotions, a title before a rank (a title raises how many cities you may hold).

Default

3

Quests belong to the account, so this runs once per account: from the first city that has any goals at all, using that city's settings. Put it in Prepend so every city agrees. It looks every 10 minutes, and again after 1 minute when it claimed something. Up to 10 quests a look.

reportstokeepGoal¶

Usage

reportstokeep <treasure> <valley> <npc5> <npc10_low> <npc10_high>

Example

reportstokeep 1 a:500 b:1 a:3800 a:6000

Values

Position	Value	Keeps a report when…
treasure	0 or 1	1: the battle found something (a medal, an item, a season token).
valley	troop:amount or 0	we lost at least that many of that troop attacking a valley.
npc5	troop:amount or 0	we lost at least that many attacking a level-5 NPC.
npc10_low	troop:amount or 0	level-10 NPC: we lost fewer than this many…
npc10_high	troop:amount or 0	…or more than this many.

A 0 (or an amount of 0) keeps every report of that kind. All five numbers are needed.

Deletes battle reports of your own farming attacks that are not worth keeping. Only reports of attacks you won are ever deleted. Always kept: a battle you lost, one where a hero of yours was taken, attacks on flats, and anything kept by the rules above. Won attacks on lords' cities are judged by the valley rule as well, so a valley rule may delete them; write 0 for the valley number to keep them all. Attacks on NPCs of levels other than 5 and 10 have no rule to keep them, so they go (unless they found treasure and treasure is 1).

Reports belong to the account: the goal runs from the first city whose goals hold a correct reportstokeep line. It opens at most 5 new reports a run without marking them read, deletes the ones to go together, and looks again after 1 minute while it finds work, or after 10 minutes when there is nothing new. One line per city.

buildGoal¶

Usage

build [?<condition>?]<type>:<level>[:<qty>][,…][?<condition>?] [more groups…]

Example

build t:9,w:9,c:9:23,b:9

build c:0:20 f:9:0

build ?w:10?q:0:0,ws:0:0 w:10

Values

Form	Meaning
type:level	At least one of that building at that level or higher.
type:level:qty	At least qty of them at that level or higher. c:9:23: 23 Cottages at level 9 or more.
type:0:qty	At most qty of that building. The weakest extra ones are taken down. q:0:0: no Quarry at all.
type:level:0	None at that level or higher: each one above is taken down to level−1. f:9:0: no Farm above level 8.
?condition?	The group it is attached to counts only while the condition holds (see below).

Levels go from 0 to 10. A building a city has only one of (everything except Cottage, Barracks, Warehouse, Farm, Sawmill, Quarry, Ironmine) is read as quantity 1, with a warning if you wrote more. type:0 on its own reads as "at most 1".

See also

plan, config building, How the builder works

A build line lists targets separated by commas. Spaces split a line into groups, and each group can carry its own condition. A city can have many build lines; they are worked one line at a time, top to bottom (including those from Prepend and Append, in the joined order).

A target counts what stands now and what is under way or waiting in the building queue, so a Cottage being raised to 5 already counts as a level 5 Cottage for planning.

The Town Hall and the Walls are never taken down: t:0:0 or w:5:0 is an error. A target that would undo an earlier line is cut back to fit it: after build c:5:10, a later build c:0:6 still keeps 10 Cottages.

researchGoal¶

Usage

research [?<condition>?]<code>:<level>[,…][?<condition>?] [more groups…]

Example

research lo:5,ho:5,com:4

research ?a:10?pr:10

Values

Research codes from the table (on this line st is Stockpile), or full names; levels 1 to 10. A type:level:qty part is an error: it belongs on a build line.

See also

config research, plan, conditions

Research lines are worked one line at a time: the next line starts once every target of the one before it is reached (or the only targets left wait on conditions). Within a line the bot tries each open target in the order written and starts the first one it can.

What the bot does for a target:

• If the next level needs other research first, that research is started instead (up to four steps back). The log shows it: "research Military Science 3 (for Archery 1)".
• If it needs a building (the Academy at a level, a Forge, a Stable, a Warehouse…), the builder raises that building first, ahead of your build lines.
• If the city cannot pay, it tries the next target on the line.
• A research another city of yours is busy with is skipped here (research is shared by the account).

One research at a time per city, and only in a city with an Academy. Research never spends what the builder is keeping for its next job. A research under way finishes free when it qualifies (freespeedup).

planGoal¶

Usage

plan <target>[,<target>…]

Example

plan c:4:9,i:4:40,b:4:14,mi:4

plan ar:8,mt:7,ho:5

Values

Build targets (type:level[:qty]) and research targets (code:level) mixed on one line, separated by commas or spaces. A building code is read first, so st is the Stable and Stockpile is sp. No conditions.

See also

config plan, build, research

A plan line is a build line and a research line in one, with a stricter order: the next plan line waits until every target of this one is finished, buildings and research together. In the examples, Archery 8 is not started until the 9 Cottages, 40 Ironmines, 14 Barracks and Mining 4 are all done.

The plan line in work, and every finished plan line above it, are placed ahead of the city's own build and research lines, so the same builder and research work on them first. A finished line keeps standing: if a building it asked for is lost, that line is back in work and the lines after it wait again. "Finished" means the buildings stand as asked now (jobs under way do not count) and each research is at its level.

The Engine view shows "plan: line 2 of 4 in work (…) — the next waits for it".

troopGoal¶

Usage

troop <code>:<amount>[,…] [/increment:<n>] [/queuetime:<hours>] [/slot:<minutes>] [/idlequeuetime:<minutes>] [/usereserved:<share>] [/usepopmax:<share>] [/traineronly:<0|1>]

Example

troop a:2m,c:1m,t:250k

troop w:5k,p:2k /queuetime:.5 /usereserved:0.5

Values

Switch	Meaning (for this line only)	Same as
/increment:n	Batch size: a share of the target below 1, or a whole number of troops.	troopincrement
/queuetime:h	Hours of work per barracks a batch.	troopqueuetime
/slot:m	The same in minutes.	troopslot
/idlequeuetime:m	Minutes a batch may take while the training hero is away.	troopidlequeuetime
/usereserved:s	Share of the kept day of troop food training may spend.	troopsusereserved
/usepopmax:s	Share of field workers to free for a batch when the city is out of idle people.	troopsusepopmax
/traineronly:0|1	Wait for the training hero for slow troops.	trooptraineronly

Amounts take k/m suffixes. An unknown switch, or one with a value that cannot be read, is an error and is left out. Writing both /queuetime and /slot is an error: /queuetime is used.

See also

config troop, traininghero, How a batch is sized

Each troop line is a stage. The city works on the first stage not yet met, and only on the types of that stage that are still short; when every type has reached its number, the next stage begins. A stage's numbers are totals, counting troops at home, in training, and out on marches from the city. They are not added to the stage before: write stage 2's numbers to include what stage 1 asked for. If troops die and a stage is no longer met, the city goes back to it.

In each pass the bot queues one batch for each short type, starting with a different type each pass so all of them move. It stops when the city has one action left for the goals that follow.

A type whose Barracks level or research is missing waits, and the Engine view says so ("Archer: needs Barracks 4"). The troop goal does not build or research what is missing: put it in your build and research lines. Each switch on a line overrides the matching config key for that line's stage only.

fortificationGoal¶

Usage

fortification <code>:<amount>[,…]

Example

fortification tra:1k,ab:500

fortification tra:5k,ab:5k,at:3k,r:1k,tre:500

Values

Code	Fortification	Wall space each	Needs
tra	Trap	1	Walls 1
ab	Abatis	2	Walls 2, Metal Casting 1
at	Archer Tower	3	Walls 3, Archery 3
r	Rolling Log	4	Walls 5, Metal Casting 5
tre	Defensive Trebuchet	5	Walls 7, Metal Casting 6

Amounts take k/m suffixes. Other spellings are in the code table.

See also

config fortification, wallqueuetime, fortsusereserved

Stages, like troop lines: the first stage not met is worked on, and its numbers are totals (built plus queued). If the city has no Walls, the builder builds them first (level 1). Higher Walls are up to your build lines.

One batch a pass, for the first short type of the stage, in the order written. Its size: about wallqueuetime of work (15 minutes by default) at the speed of the current mayor (its politics, with Construction), or the whole shortfall when one piece takes under a second; never more than the wall space left (built and queued pieces both take space), and never more than the resources allow, keeping a day of troop food unless fortsusereserved says otherwise.

The Walls work through at most 5 batches at a time; with 5 queued the goal waits. If the first short type's requirement is missing, the whole stage waits ("fortifications: stage 2/2: Abatis needs Walls 2"); it does not skip to the next type. So write the types you can already build first, as in the example.

trainingheroGoal¶

Usage

traininghero <hero name> [<min_seconds>] [<max_seconds>]

Example

traininghero Arthur

traininghero Arthur 600 3600

Values

hero name: one word, any case. min_seconds: the least time it stays in a city that still needs troops. max_seconds: the most. A fourth number is accepted and does nothing.

Default

min 600 seconds (10 minutes); no max

See also

trooptraineronly, troopdelbadque, nomayor, feastinghallspace

A hero with high attack trains troops fast when it is mayor (on Citavon each attack point cuts training time by 0.5%, and with enough attack and Military Science a troop trains in under a second: instant). The training hero goes round your cities that still have troop stages to finish, and is mayor in each while it is there.

How it moves:

1. In the city where it is, it becomes mayor (unless config nomayor:1) and troops are queued at its speed.
2. It stays at least min_seconds, unless every troop stage there is met. It leaves when the stages are met or after max_seconds.
3. It goes to the next city, in the account's city order, whose troop stage is not met (judged by that city's own goals). If no other city needs troops, it stays.
4. It travels as a reinforcement with one troop beside it (the cheapest the city has of Worker, Warrior, Scout, Pikeman, Swordsman, Archer), after standing down as mayor. The move needs a free Rally Spot slot and counts as task t for processingpolicy and rallypolicy.

While War Town Mode 2 is on for its city, it stays where it is.

config troopincrementConfig¶

Usage

config troopincrement:<n> · line switch /increment:<n>

Example

config troopincrement:0.01

config troopincrement:5k

Values

0 off (batches by time); a share below 1, e.g. 0.01 = batches of 1% of the target; a whole number of 2 or more = that many troops a batch (k/m allowed); 1 accepted (NEAT's ratio mode) but here it sizes batches by time, the same as 0, and gives troopidlequeuetime a default of 1 minute. Fractions above 1 are an error.

Default

0 (batches by time)

Sets the size of each troop batch instead of the time-based size. With a share, the batch is that share of the stage's number for the type (rounded up), so troop a:100k with 0.01 queues 1,000 Archers at a time. The batch is still cut to what is short, the idle population, the resources and the barracks' room.

config troopqueuetimeConfig¶

Usage

config troopqueuetime:<hours> · line switch /queuetime:<hours>

Example

config troopqueuetime:2

config troopqueuetime:.5

Values

Hours, a plain number; fractions allowed. At least one minute is used.

Default

30 minutes (when neither this nor troopslot is set)

See also

troopslot

How much work each barracks gets in one batch when batches are sized by time: the batch holds enough troops to keep every barracks with room busy for this long, at the current mayor's speed. Longer batches mean fewer actions; shorter ones let a training hero arriving later make more of the work fast. Ignored when troopincrement sets the size. It beats troopslot when both are set.

config troopslotConfig¶

Usage

config troopslot:<minutes> · line switch /slot:<minutes>

Example

config troopslot:20

Values

Minutes, a plain number (30m is an error).

Default

30

See also

troopqueuetime

The batch time of troopqueuetime, in minutes. If both are set, troopqueuetime is used (on one line, setting both is an error). On a troop line, /queuetime beats /slot, and either beats both config keys.

config troopidlequeuetimeConfig¶

Usage

config troopidlequeuetime:<minutes> · line switch /idlequeuetime:<minutes>

Example

config trooptraineronly:0,troopidlequeuetime:10

Values

Minutes, a plain number. 0 = nothing slow is queued while the hero is away.

Default

0 (1 when troopincrement is 1)

See also

trooptraineronly, traininghero

Only matters in a city with a traininghero line while the hero is elsewhere, and only with trooptraineronly:0. Then troops that would not train instantly are queued in short batches of this many minutes of work, and only into barracks with nothing queued at all, so the barracks are nearly empty when the hero arrives. With 0 they wait for the hero.

config trooptraineronlyConfig¶

Usage

config trooptraineronly:<0|1> · line switch /traineronly:<0|1>

Example

config trooptraineronly:0

Values

1 while the training hero is away, queue only troops that train instantly; 0 allow short batches (troopidlequeuetime).

Default

1

See also

traininghero

In a city with a traininghero line, while the hero is in another city: with 1 (the default) only troops that train instantly under the city's own mayor are queued; the rest wait for the hero, and the Engine view says "waits for the training hero Arthur". This keeps the barracks free so the hero's fast batches go in when it arrives. Cities without a traininghero line are not affected.

config troopsusereservedConfig¶

Usage

config troopsusereserved:<share> · line switch /usereserved:<share>

Example

config troopsusereserved:0.5

Values

A share from 0 to 1 (0.5 = 50%).

Default

0 (the whole day of food is kept)

See also

fortsusereserved

Training always keeps a day's worth of the city's troop food upkeep in store, so that troops do not starve because of new troops. This setting says what share of that day's food training may still spend: 0 keeps it all, 1 lets training spend it all.

config troopsusepopmaxConfig¶

Usage

config troopsusepopmax:<share> · line switch /usepopmax:<share>

Example

config troopsusepopmax:0.2

Values

A share from 0 to 1. 0 = off.

Default

0

See also

production

Troops are made from idle population. When the city's idle people fall under 5% of its population, this frees workers from the fields for a moment: each resource's worked share is lowered by this share (0.2 = a fifth fewer workers), the batches are queued, and the shares are put back straight after, in the same pass. It lets a city that is full of workers keep training.

config reservedbarrackConfig¶

Usage

config reservedbarrack:<0|1>

Example

config reservedbarrack:1

Values

1 keep one barracks free; 0 off.

Default

0

Keeps the city's best barracks (the highest level; among equals, the last plot) free of goal batches, so you or a script can always train something there at once. Goal batches then go into one of the other barracks each, not spread over all. While the city is under attack (an attack on its way, or a battle there a short time ago) the reserved barracks is used too.

config troopdelbadqueConfig¶

Usage

config troopdelbadque:<0|1>

Example

config troopdelbadque:1

Values

1 on; 0 off.

Default

0

See also

traininghero

A batch keeps the training time it was queued with. When the training hero becomes mayor, batches queued earlier under a weaker mayor are slow by comparison. With troopdelbadque:1, while the training hero is mayor, the bot cancels a waiting batch (not the one training now) that is more than half as slow again as the hero would make it, plus 5 minutes: the one that wastes the most time first. One cancel per pass, and a troop type at most once an hour. The troop goal then queues the troops again at the hero's speed.

Citavon gives back most of a cancelled batch's cost (95%), not all of it. Without a training hero, or while it is not mayor, this setting waits ("troopdelbadque: waits for the training hero as mayor").

config feastinghallspaceConfig¶

Usage

config feastinghallspace:<n>

Example

config feastinghallspace:1

Values

A number of hero slots, 0 or more.

Default

0

See also

fasthero, traininghero

Keeps n slots of the Feasting Hall free from hiring by fasthero, plus one more while the training hero is away from this city (once the key is set at all, even to 0), so it always has a place to come back to. While slots are kept free, fasthero never fires a hero to make room. It only affects fasthero: without that setting it does nothing, and it never stops you or a script from hiring.

config wallqueuetimeConfig¶

Usage

config wallqueuetime:<hours>

Example

config wallqueuetime:1

Values

Hours, a plain number; fractions allowed (.25 = 15 minutes).

Default

15 minutes

See also

fortification

How much work one fortification batch holds, at the speed of the current mayor (its politics, with Construction). A fortification that builds in under a second is queued for its whole shortfall. There is no switch for it on the fortification line.

config fortsusereservedConfig¶

Usage

config fortsusereserved:<share>

Example

config fortsusereserved:1

Values

A share from 0 to 1.

Default

0 (the whole day of food is kept)

See also

troopsusereserved

As troopsusereserved, for fortifications: what share of the day of troop food kept in store fortification batches may spend. When food is what stops a batch, the Engine view says how much is being kept.

config nomayorConfig¶

Usage

config nomayor:1

Example

config nomayor:1

Values

1 the bot leaves the mayor alone; anything else (or no line) the bot picks the mayor.

Default

Off: the bot picks the mayor.

See also

traininghero, trainpol

With nomayor:1 the bot never appoints, swaps or removes this city's mayor. Use it when you want a particular hero in office that is not the best politician, for example an attack hero for fast training without a traininghero line.

config heroConfig¶

Usage

config hero:<0|1>

Example

config hero:1

Values

1 (or more) level heroes and place their points; 0 off.

Default

Off.

See also

heropoints, nolevelheroes

Raises every hero in the city that has the experience for its next level, one level at a time, and places unspent points (heropoints says where; without a line, into the hero's highest stat). It stops early in a pass when the city's actions for that pass run low, and carries on next pass.

It never uses items for this (no experience or reset items).

nolevelheroesGoal¶

Usage

nolevelheroes <hero string>  or  nolevelheroes /reset

Example

nolevelheroes Merlin,Arthur

nolevelheroes any:base>=75

Values

/reset forgets the nolevelheroes lines above it (useful when the account's prepend goals set some and this city wants others).

Default

None: every hero is levelled.

See also

config hero, hero strings

The heroes it matches are left to you: config hero:1 neither levels them nor places their points. Use it for a hero you want to build by hand. Several lines add up (a hero matched by any of them is skipped).

heropointsGoal¶

Usage

heropoints <hero string> <stage> [<stage> …]  or  heropoints /reset

Example

heropoints any:politics>attack pol

heropoints Lancelot att:500 att:1000,int:300 att

heropoints any:base>=70 int:200 off

Values

Part	Meaning
hero string	One word (no spaces): which heroes this line is for. See hero strings.
stage	One word: one or more targets joined by commas, worked together. Stages are worked left to right.
stat:cap	Raise that stat until it reaches cap (the stat's total, not a number of points). Stat words: attack att atk power; politics pol management; intel int intelligence stratagem.
stat or stat:*	No cap: every point left goes there.
stat:any	Read as a cap of 0, so that target takes nothing.
off / none	Stop here: points beyond the stages before it stay unspent.
/reset	Forgets the heropoints lines above it.

Default

No line: every point into the hero's highest stat.

See also

config hero, nolevelheroes

Only works with config hero:1. For each hero the first heropoints line whose hero string matches it is used; a hero no line matches gets the default. Within a stage, the points are shared out in proportion to what each target still needs, so att:1000,int:300 moves both stats toward their caps together. A stage whose targets are all reached is skipped.

If the last stage has no open-ended target (and is not off), whatever is left after the last stage goes into the hero's highest stat. Worked example, for heropoints Lancelot att:50 att:100,int:850 att on a hero with attack 40, intelligence 800 and 200 points: stage 1 gives 10 to attack (to 50); stage 2 needs 50 attack and 50 intelligence and gets both; stage 3 puts the last 90 into attack. Result: attack 190, intelligence 850.

config fastheroConfig¶

Usage

config fasthero:<base>

Example

config fasthero:65

Values

The lowest hero base worth hiring (a number). 0 is off.

Default

Off.

See also

keepheroes, feastinghallspace, hero strings (base)

Each pass the bot looks at the city's Inn. If a hero there has a base (its best stat as it was born, before points) of at least this number, the best such hero is hired, as long as the city has the gold for the fee.

If the Feasting Hall is full, the bot first fires the weakest idle hero that no keepheroes rule keeps and whose base is lower than the Inn hero's; the hire follows on a later pass. If every hero is kept or better, the Inn hero waits. With feastinghallspace set, that many slots stay empty (one more while the training hero is away): hiring stops there and nobody is fired to make room.

keepheroesGoal¶

Usage

keepheroes <hero string> [/always]  or  keepheroes /reset

Example

keepheroes any:level>=60|any:base>=70

keepheroes Merlin,Arthur|any:politics>=300

keepheroes any:base>=68 /always

Values

/always fire, one a pass, every idle hero no rule keeps, even when no hire needs the slot. /reset forgets the keepheroes lines above it.

Default

any:level>=50|any:base>=69 (used while the city has no keepheroes line).

See also

fasthero, herofirelimit

Heroes that match are never fired by the bot. Several lines add up: a hero kept by any line is kept. Without /always this line only matters when config fasthero wants a slot.

herofirelimitGoal¶

Usage

herofirelimit <level>

Example

herofirelimit 40 (the same as keepheroes any:level>=40)

See also

keepheroes

The older way to write a keep rule by level. It is read as keepheroes any:level>=<level> and adds to the city's other keepheroes lines. The level must be 1 or more. Write it once per city (a second line replaces the first).

keepcapturedheroesGoal¶

Usage

keepcapturedheroes <hero string>  or  keepcapturedheroes /reset

Example

keepcapturedheroes any:level>=100|any:base>=72

keepcapturedheroes none (release every prisoner)

Values

/reset forgets the lines above it; if nothing is left, the built-in rule any:level>=200|any:base>69 is used.

Default

No line: no prisoner is ever released by the bot.

See also

hero strings

This is about enemy heroes your city holds prisoner. Once the city has a keepcapturedheroes line, the prisoners it does not match are released, the lowest level first, one every 10 minutes per city. The kept ones stay in your prison. When a hero string uses best or worst here, it compares against the other prisoners.

The old line capturedfirelimit <level> is read as keepcapturedheroes any:level>=<level>.

spamheroesGoal¶

Usage

spamheroes <hero string>  or  spamheroes /reset

Example

spamheroes any:level<30,base<=60

spamheroes Spam*

Values

/reset forgets the lines above it.

Default

any:base<=69,level<50

See also

spamattack, loyaltyattack, capture

Says which heroes of the city the background attack commands may send with their waves: spamattack, loyaltyattack and capture. Only idle heroes are used. spamattack also wants the hero at 100 loyalty. The goal does nothing by itself; it only feeds those commands. Several lines add up.

homeheroesGoal¶

Usage

homeheroes <n>

Example

homeheroes 2

Default

0: every idle hero may go out.

See also

npcheroes, valleyheroes

The city's n best heroes never lead an NPC run or a valley run. "Best" is by the hero's highest stat (attack, politics or intelligence), counting every hero in the city that is not a prisoner, the mayor and heroes out marching included. So if your mayor is your best hero, it is one of the n.

keepherobuffGoal¶

Usage

keepherobuff <hero> <excalibur|wealth|artofwar> [/below:<n>]

Example

keepherobuff Lancelot excalibur

keepherobuff Merlin wealth /below:1500

Values

Word	Item	Raises
excalibur, blade	Champion's Blade	attack
wealth, wealthofnations, statecraft	Book of Statecraft	politics
artofwar, treatise	Treatise on Strategy	intelligence

/below:<n>: only while the hero's own stat (without the item) is under n.

Default

No line: no item is used.

Keeps the 7-day item running on the hero: whenever nothing is raising that stat on it, one item is used from your stock. The city that holds the hero does it. The hero name is one word and must be the exact name (capitals do not matter). It never buys the item: with none in stock the Engine view says so and it waits. One line per hero and item; write several lines for several.

config npcConfig¶

Usage

config npc:<level>

Example

config npc:5

Values

The lowest NPC level to farm, 1-10. 0 is off.

Default

Off.

See also

npctroops, how a camp is picked

Turns NPC farming on for the city. The bot farms the highest level it can supply and works down to this level as troops or heroes run short or no camp is due. Only levels with an npctroops line are ever farmed. npc:5 with npctroops for levels 5 and 10 farms 10 first, then 5.

config npclimitConfig¶

Usage

config npclimit:<days>

Example

config npclimit:3

Values

Days of food (fractions allowed). 0 off.

Default

Off.

Stops sending NPC attacks while the city holds at least this many days of its troops' food use and its food income is not negative. Farming starts again once the food drops below it. A city whose troops eat nothing never stops this way.

config farmingcycleConfig¶

Usage

config farmingcycle:<hours>

Example

config farmingcycle:6

Values

Hours (fractions allowed) between two hits on the same camp.

Default

8.4 hours.

See also

farmingpolicy, cycles, valleyfarming

The cycle for every level that has no farmingpolicy cycle of its own and is not in training mode. It is also the rest time between hits on one valley for valley farming.

config farmingcycleminConfig¶

Usage

config farmingcyclemin:<hours>

Example

config farmingcyclemin:4

Values

Hours, more than 0.

Default

None (1 hour with smartfarming:2 or 3).

Levels 1-5 only. When no camp of a level is past its full cycle, a camp that has rested at least this long may be hit: the one that has rested longest. Keeps your teams busy when you have few camps nearby. Ignored if it is not shorter than the cycle, and in training mode.

config smartfarmingConfig¶

Usage

config smartfarming:<0-3>

Example

config smartfarming:2

Values

2 or 3: a 1-hour minimum cycle on levels 1-5 (as farmingcyclemin:1), unless farmingcyclemin is set. 0 and 1 change nothing.

Default

0.

On the old server, modes 1 and 3 also sized each run to the camp's loot. That part does nothing here: the bot can't know how far a camp has refilled, so it always sends the full npctroops army.

config trainingConfig¶

Usage

config training:<0|1|2>

Example

config training:1

Values

1 levels 1-9 on a 1-hour cycle. 2 the same, meant to leave transporters home (at present they still go). 0 off.

Default

0.

See also

training mode, training10

Overrides every other cycle for levels 1-9. The camps' troops grow back within the hour, so each hit is a full battle and full experience for the hero. The camps' resources do not refill that fast, so expect smaller loot.

config training10Config¶

Usage

config training10:<0|1>

Example

config training10:1

Default

0.

Level-10 camps on a 1-hour cycle, overriding every other cycle for level 10. You still need an npctroops 10 line.

config ballsusedConfig¶

Usage

config ballsused:<n>  or the old line  ballsused <l1>,<l2>,<l3>,<l4>,<l5>

Example

config ballsused:50

ballsused 25,50,170,250,500

Values

A whole number of ballistas.

Default

0.

As a config key: that many ballistas are added to every NPC run whose npctroops line names no ballistas (at every level). The city must have them.

As its own line (the old form), the five numbers are the ballistas for levels 1 to 5, and each is read as an npctroops line: ballsused 25,50,170,250,500 becomes npctroops 1 b:25, npctroops 2 b:50 and so on. A 0 is refused (it would send nothing but transport), so that level keeps its own line.

config trainintConfig¶

Usage

config trainint:<0|1>

Example

config trainint:1

Default

0: intelligence heroes stay home.

An intelligence hero (one whose intelligence is higher than both its attack and its politics) does not lead NPC runs unless this is 1. Applies to NPC farming only, not to valley runs.

config trainpolConfig¶

Usage

config trainpol:<0|1>

Example

config trainpol:1

Default

0: the spare politics hero stays home.

The idle hero with the most politics, if it has more than the mayor (or there is no mayor), is kept home so it can take the office. With trainpol:1 it may farm like any other hero. Applies to NPC farming only.

config mapscanConfig¶

Usage

config mapscan:<0|1>

Example

config mapscan:1

Accepted so old goal files read cleanly; it does nothing. Citavon Bot reads the map live whenever it looks for camps or valleys, so there is no saved map to fill.

npctroopsGoal¶

Usage

npctroops [level] <troops>

Example

npctroops 5 a:2k,c:500,t:100

npctroops a:800,t:50 (levels 1-5)

npctroops 10 a:60k,b:5k,cp:1k

Values

Troops as code:amount joined by commas: w warriors, wo workers, s scouts, p pikemen, sw swordsmen, a archers, c cavalry, cata cataphracts, t transporters, b ballistas, r rams, cp catapults. Amounts take k and m.

Default

None: a level with no line is not farmed.

The exact army an NPC run at that level takes. A line with no level covers levels 1-5. Levels 6-10 need a line each. Before sending, the city must have this army at home on top of what npclimits keeps back; if not, the bot tries a lower level. Add transporters for more room to carry loot home.

npcheroesGoal¶

Usage

npcheroes [level] <heroes>

Example

npcheroes any:level>=10

npcheroes 10 !Merlin,any

npcheroes 6 Lancelot,Gawain|any:att>=300

Default

any

See also

homeheroes, trainint, trainpol, npc10heroes

Who may lead NPC runs at that level. A line with no level covers levels 1-5; levels 6-10 with no line of their own take any hero. The bot picks, among the city's idle heroes, the one with the highest attack (hero items counted here) that the line allows. Always left at home: the homeheroes, heroes already sent this pass, intelligence heroes (unless trainint:1), and the spare politics hero (unless trainpol:1). The mayor is never idle, so it never goes.

npc10heroesGoal¶

Usage

npc10heroes <heroes>

Example

npc10heroes Lancelot,Gawain

See also

npcheroes

The older spelling of npcheroes 10 <heroes>, read the same way (the editor notes it). If the city has both, the npcheroes 10 line is used.

npclimitsGoal¶

Usage

npclimits [level] <troops>

Example

npclimits a:20k,p:10k (levels 6-10)

npclimits 3 a:5k

Default

Nothing is kept back.

Troops that must stay at home when the bot farms that level. A run goes only if the city holds the npctroops army plus these. A line with no level covers levels 6-10 (unlike npctroops). Same troop codes as npctroops.

npcteamsGoal¶

Usage

npcteams <n>

Example

npcteams 5

Default

10.

See also

rallypolicy

At most this many attacks out from the city at once before NPC farming waits. It counts every attack of the city on its way or coming back (valley runs and attacks you or a script sent too), but not troops camped somewhere. npcteams 0 stops NPC farming. Valley farming and medal hunting use the same number for their own catch-and-release runs (there, 0 counts as 10). The Rally Spot's free slots still limit everything.

npclistGoal¶

Usage

npclist [level] <x,y> [<x,y> …]

Example

npclist 5 101,220 104,225 98,231

With a list for a level, the bot farms only those camps at that level, nearest first, and does not look at the map for that level. A list with no level is used for every level.

npcboundsGoal¶

Usage

npcbounds [level] <Xmin> <Xmax> <Ymin> <Ymax>

Example

npcbounds 90 130 200 240

npcbounds 10 0 200 0 200

Only camps inside this box are farmed (the distance limits still apply too). With 4 numbers it covers every level; with 5, the first is the level. The two X (or Y) values may be written in either order.

farmingpolicyGoal¶

Usage

farmingpolicy [level] [/level:<n>] [/mindistance:<miles>] [/maxdistance:<miles>] [/farmingcycle:<hours>]

Example

farmingpolicy 5 /maxdistance:15 /farmingcycle:6

farmingpolicy /level:10 /mindistance:5 /maxdistance:25 /farmingcycle:12

Values

Switch	Meaning
level or /level:n	The NPC level this line is for. No level: every level without a line of its own.
/mindistance:	Skip camps nearer than this (miles). Default 0.
/maxdistance: (or /distance:)	Skip camps further than this. Default distancepolicy's first number, else 10.
/farmingcycle: (or /cycle:, /maxcycle:, /cyclemax:)	Hours between hits on one camp of this level. Beats config farmingcycle, loses to training mode.
/mincycle: /cyclemin: /safeballs: /teams:	Accepted from old files; they do nothing. Use farmingcyclemin and npcteams.

See also

cycles

Distance and cycle for one NPC level. The bot never looks further than 60 miles, whatever the maximum.

distancepolicyGoal¶

Usage

distancepolicy <npc miles> [<npc-building miles>] [<valley miles>]

Example

distancepolicy 12 8 15

distancepolicy 20

Values

Number	Used by
1st	NPC farming's reach (when no farmingpolicy gives one) and acquireflats.
2nd	buildnpc's reach for flats (when no npcbuildpolicy gives one).
3rd	Valley goals: valley, valleyfarming (without its own line), safevalleyfarm; hunting looks three times as far.

Default

10 miles for each.

How far out, in miles, the goals look. Old files may carry more numbers after these; they are ignored. Write the numbers plainly. /npc:15 is also read as the first number, but then the numbers after it are not read in the right places, so use it only on its own. One line per city: a second one replaces the first. The bot never looks further than 60 miles.

excludelistGoal¶

Usage

excludelist <x,y> [<x,y> …]

Example

excludelist 120,340 122,341

NPC farming never attacks these tiles, at any level, even from an npclist. Several lines add up. Use it for an ally's camp or one you are taking over. The old npcexcludelist, npc10excludelist and noabandonflats lines are read as excludelist. It does not affect valley goals.

config buildnpcConfig¶

Usage

config buildnpc:<0|1-5|10|15|20>

Example

config buildnpc:5

Values

1-5 flats of that level; 10 level 10; 15 levels 5 and 10; 20 every level 1-10; 0 off.

Default

Off.

See also

buildnpcpolicy, npcbuildpolicy, buildnpclist

Turns NPC building on for the city, for flats of those levels. A flat keeps its level while you hold it, and the new NPC gets that level. Any flat the city already holds at a wanted level is used too, including one taken with acquireflats.

buildnpcpolicyGoal¶

Usage

buildnpcpolicy [/maxconcurrent:n] [/keepcities:n] [/maxres:n] [/maxtroops:n] [/minage:min] [/maxage:h] [/perday:n]

Example

buildnpcpolicy /maxconcurrent:2 /keepcities:3 /perday:6

Values

Switch	Default	Meaning
/maxconcurrent:	1	Flats being turned into NPCs at once (founded, not yet given up).
/keepcities:	2	Never give up a city while the lord has this many cities or fewer.
/maxres:	5m	A new city holding more than this of any resource (gold too) is not given up yet.
/maxtroops:	250	Accepted, but does nothing: any troop in the city keeps it.
/minage:	5	Minutes a new city stands before it is given up.
/maxage:	24	Hours: a city founded longer ago is never given up.
/perday:	4	Cities given up in any 24 hours, for the whole lord.

The safety limits of NPC building. One line per city; switches you leave out keep their defaults. Numbers take k, m, b. An unknown switch turns the line red in the editor; the other switches on it still count.

npcbuildpolicyGoal¶

Usage

npcbuildpolicy [/level:<n|a-b>] [/mindistance:<miles>] [/maxdistance:<miles>]

Example

npcbuildpolicy /level:5 /mindistance:3 /maxdistance:8

npcbuildpolicy /level:1-4 /maxdistance:5

Values

/level: one level or a range; left out, the line covers every level. /mindistance: default 0. /maxdistance: default the minimum plus 1.

Default

No line: 0 to distancepolicy's second number (else 10) miles.

How far out flats of each level are taken for NPC building. Several lines may be written; for each level the first line that covers it is used. Watch the default maximum: npcbuildpolicy /mindistance:6 alone means 6 to 7 miles.

buildnpclistGoal¶

Usage

buildnpclist <x,y> [<x,y> …]

Example

buildnpclist 105,214 107,216

Only these flats are taken for NPC building (they must still be free, of a wanted level and within reach). Several lines add up.

config valleyConfig¶

Usage

config valley:<level>

Example

config valley:8

config valley:8,valleymin:5

Values

Valley level 1-10; 0 off.

Default

Off.

See also

valleymin, valleytroops, distancepolicy

Captures and holds valleys that feed the city's main resource. The bot counts the city's resource buildings and picks the kind it has most of: farms mean lakes, sawmills forests, quarries deserts, iron mines hills (with no resource buildings, lakes). One capture at a time, within distancepolicy's third number (default 10 miles), with the capture army for the level.

Without valleymin only valleys of exactly this level are taken. With it, the bot takes the nearest free valley of that kind whose level is anywhere from valleymin to this level. It doesn't hold out for the highest level. It stops when the city's valley slots are full (flats you hold don't count toward that).

config valleyminConfig¶

Usage

config valleymin:<level>

Example

config valley:9,valleymin:6

Values

Level 1-10, not above valley.

Default

The same as valley.

Only works with config valley. It sets the lowest level worth capturing, and it turns on upgrading: once every valley slot is full, the bot lets go of your lowest held valley below the valley level as soon as it sees a free valley of the right kind at a higher level (within the range), and captures that one on a later pass.

config acquireflatsConfig¶

Usage

config acquireflats:<0|1|2>

Example

config acquireflats:1

Values

1 keep one flat held; 2 fill every free slot with flats; 0 off.

Default

Off.

Captures the nearest free flat (any level) within distancepolicy's first number (default 10 miles), one at a time, with the capture army for its level. It stops when it holds enough flats or the slots are full. Held flats are where you found new cities, or what buildnpc builds on.

config abandonflatsConfig¶

Usage

config abandonflats:<0|1>

Example

config abandonflats:1

Accepted, but does nothing: the bot never lets flats go for this. On the old server it released held flats before maintenance so they could level up. The Engine view says it has nothing to do.

config abandonConfig¶

Usage

config abandon:<0|1>

Example

config abandon:1

Default

Off.

Strips a city you mean to give up or hand over. Every pass it cancels the building under way, cancels the troops in training, demolishes every fortification, sets the tax to 100%, and sends every troop (as reinforcements) to your nearest other city. While it is on, the city's other valley goals do nothing. It does not give the city up; you do that yourself.

config huntingConfig¶

Usage

config hunting:<level>

Example

config hunting:5

Values

Valley level 1-10; 0 off.

Default

Off.

See also

huntingpos, huntingtype, medal hunting

Medal hunting on one valley. The valley is the one at huntingpos if set, otherwise the nearest free valley of this level of the huntingtype kind (default: the city's own kind, as for config valley). The bot looks up to three times distancepolicy's valley miles (30 by default). Each pass, if no attack of yours is on its way to it, a new run goes with the next free hero, and a win is let go at once. There is no rest time between hits.

With huntingpos, the level in this line is not checked against the valley: the run takes the army for the valley's real level.

config valleyfarmingConfig¶

Usage

config valleyfarming:<level>

Example

config valleyfarming:4

Values

Valley level 1-10; 0 off.

Default

Off.

See also

valleyfarming (the miles line), farmingcycle

Catch-and-release runs on every free valley of this level in reach, nearest first. Reach is the valleyfarming miles line if you have one, otherwise the city's own kind of valley within distancepolicy's valley miles. Several runs may go in one pass, until npcteams runs are out, the city's actions for the pass run low, or a run can't go. Each valley rests farmingcycle hours (8.4 by default) between hits.

valleyfarmingGoal¶

Usage

valleyfarming <forest> <desert> <hill> <swamp> <grassland> <lake>

Example

valleyfarming 15 0 0 10 10 20

Values

Six numbers, miles for each kind of valley in that order; 0 leaves that kind out.

Default

No line: only the city's own kind, within distancepolicy's valley miles.

Which kinds of valley config valleyfarming hits, and how far for each. The example farms forests up to 15 miles, swamps and grasslands up to 10, lakes up to 20, and no deserts or hills. It wants exactly six numbers. With fewer, the line turns red in the editor but is still used, and the missing kinds count as 0 (left out). Numbers past the sixth are ignored. One line per city.

safevalleyfarmGoal¶

Usage

safevalleyfarm <level>[,<level>…]  (also spelled safevalleyfarming)

Example

safevalleyfarm 3,4,5

safevalleyfarming 6

Values

One or more valley levels 1-10, joined by commas or spaces.

Catch-and-release with a look first. Within distancepolicy's valley miles, for free valleys (not flats) of these levels:

1. The bot scouts a valley it hasn't scouted in the last 6 hours, with up to 10 scouts, one valley a pass.
2. When the scout report comes in, it adds up the troops seen (a rough count like "Horde" counts as its top number). The valley is judged safe if the scouting succeeded and it saw no more than half the hunting army for that level.
3. A safe valley not hit in the last hour gets a hunting-army run (or valleytroops), and a win is let go at once. Each valley is scouted again after 6 hours and judged afresh.

It needs scouts in the city. It judges the troops only, not the valley's hero.

huntingposGoal¶

Usage

huntingpos <x,y>

Example

huntingpos 143,287

See also

config hunting

The exact valley config hunting hunts on. It beats huntingtype. It must be within three times the valley miles of the city.

huntingtypeGoal¶

Usage

huntingtype <forest|desert|hill|swamp|grassland|lake>

Example

huntingtype swamp

Values

Short forms: fo, d, h, s, g / grass, l; plurals work. Flats are refused.

Default

The city's own kind (as for config valley).

The kind of valley config hunting looks for, when there is no huntingpos.

valleyheroesGoal¶

Usage

valleyheroes <hero string>

Example

valleyheroes any:level<40

valleyheroes !Merlin,any:attack>=200

Default

any

See also

hero strings, homeheroes

Who may lead valley and flat runs: capture, acquireflats, buildnpc's captures, hunting and both kinds of valley farming. It takes a full hero string, and several lines add up. Among the idle heroes it allows (less the homeheroes), the one with the highest attack goes.

valleylimitGoal¶

Usage

valleylimit <troops>

Example

valleylimit a:20k,w:10k

Default

Nothing kept back.

Troops that stay home whatever valley runs want: a run goes only if the city has its army plus these. One word, no spaces (troop codes as in npctroops). One line per city.

valleytroopsGoal¶

Usage

valleytroops <level> <troops>

Example

valleytroops 8 a:15k,w:1,p:1,sw:1,c:1,b:500

Default

The built-in armies.

The army for every valley and flat run at that level: capture, acquireflats, buildnpc's captures, hunting and farming all use it. (There is no separate capture and hunting line.) The troops are one word with no spaces. Write one line per level; for the same level, the last line wins.

requestresourcesGoal¶

Usage

requestresources <from> <type> <localAmount> <remoteAmount> [minBatch] [maxBatch] [troopType] [/below:<amount>] [/maxdist:<tiles>]

Example

requestresources any food 50m 100m 5m * t

requestresources Rome|Carthage iron 20m 5m 1m 10m cav /below:10m /maxdist:40

Values

Value	Meaning
from	any, a city name or x,y of your own cities, several joined by |.
type	food (f), wood (w, lumber, l), stone (s), iron (i), gold (g).
localAmount	Ask only while this city holds less than this (counting transports on their way), and never fill it past this. *: no limit, take everything the senders can spare.
remoteAmount	Never take a sending city below this. *: a sender may be emptied.
minBatch	Don't send less than this at a time, unless this city is down to half of localAmount or less. Optional; * or left out: no minimum.
maxBatch	At most this much a send. Optional; * or left out: as much as one march can carry.
troopType	What carries it. Optional; default transporters (t). Any troop word works, e.g. cav.
/below:	Only start asking once the city is under this. Once a send has gone out, it keeps asking until localAmount is reached, then waits for the city to drop under /below again.
/maxdist:	Only senders at most this many tiles away. /40 is short for /maxdist:40.

Default

None: the first four values are required.

See also

sendresources, keepresources, requesttroops

Each pass, each line is checked once. If the city holds localAmount or more, counting what is already on its way, nothing happens. Otherwise the bot looks at every city named in from, except this one, cities in War Town Mode, and cities further than /maxdist. A city can send if it holds more than remoteAmount, has at least one of the carrier troop at home, and has a Rally Spot with a free slot. Of those, the one with the most to spare sends.

The amount is the smallest of: what is missing up to localAmount, what the sender has above remoteAmount, maxBatch, and what one march can carry. The march uses the sender's carriers (up to the Rally Spot's limit), but only as many as the load needs. The food the carriers eat on the way is taken out of the hold first. If the amount is under minBatch and this city is not at half of localAmount or less, the line waits.

After a send the line rests for 30 seconds. After that the transport is counted as on its way, so the next pass only asks for the rest.

The /slots and /steps switches are accepted on this line but change nothing.

requesttroopsGoal¶

Usage

requesttroops <from> <troop> <localAmount> <remoteAmount> [minBatch] [maxBatch] [/slots:N] [/maxdist:<tiles>]

Example

requesttroops any a 200k 50k 10k

requesttroops 210,377 cata 50k 0 5k 20k /slots:2

Values

Value	Meaning
from	any, a city name or x,y of your own cities, joined by |.
troop	A troop word: wo worker, w warrior, s scout, p pikeman, sw swordsman, a archer, t transporter, c cavalry, cata cataphract, b ballista, r battering ram, cp catapult (full names and plurals work too).
localAmount	Ask while this city has fewer than this at home, counting reinforcements on their way; never fill it past this. *: no limit.
remoteAmount	Never take a sending city below this. *: down to 0 (but see below).
minBatch	Don't send fewer than this at a time, unless this city is at half of localAmount or less.
maxBatch	At most this many a send.
/slots:	How many marches may be on the road at once between one sender and this city (going or coming back). Default 1.
/maxdist:	Only senders at most this many tiles away (/40 works too).

Default

/slots:1; no batch limits.

See also

sendtroops, keeptroops, recall

The bot lists your other cities that have troops of that type to spare, nearest first. A sender's spare is its troops at home minus the larger of remoteAmount and the sender's own requesttroops level for the same troop, so a sender never gives away troops it would ask for straight back. The nearest sender that has fewer than /slots marches on the road to this city sends. Cities in War Town Mode and cities beyond /maxdist are skipped.

The troops go as a reinforcement and join this city. One send carries at most the Rally Spot's limit, and only troops at home count. Troops in training, out on a march or in another city are not counted on either side.

sendresourcesGoal¶

Usage

sendresources <to> <type> <localAmount> <remoteAmount> [minBatch] [maxBatch] [troopType] [/slots:N] [/maxdist:<tiles>]

Example

sendresources any stone 30m 20m 2m 10m

sendresources 155,402 food 200m * 10m 50m t (another lord's city: remoteAmount must be *)

Values

Value	Meaning
to	any (all your other cities), a city name, or x,y, joined by |. An x,y that is not your city is another lord's.
type	food, wood, stone, iron or gold (or f w l s i g).
localAmount	What this city keeps. Only what is above it is sent.
remoteAmount	Fill a receiver up to this at most. *: no limit. Must be * for a city that isn't yours, because the bot can't see its stock.
minBatch	Don't send less than this at a time, unless the receiver is at half of remoteAmount or less.
maxBatch	At most this much a send.
troopType	What carries it; default transporters.
/slots:	Marches on the road at once between this city and one receiver (going or coming back). Default 1.
/maxdist:	Only receivers at most this many tiles away.

Default

/slots:1; carriers: transporters.

See also

keepresources, requestresources

The surplus is what the city holds above localAmount. If the city also has a requestresources line for the same resource, it keeps at least that line's level too (its /below if it has one, else its localAmount). With no surplus, nothing happens.

Receivers are tried nearest first. A receiver is skipped when it already has /slots marches on the road from this city, or when it is full. For your own city "full" means it holds remoteAmount (counting what is on its way). For a receiver reached through any, it also means the level at which that city's own push line for the resource would send it on. The amount is the smallest of the surplus, the receiver's room and maxBatch. The first receiver that can take a send gets it: one send per line per pass.

A quarter of the city's carriers (at most 2,000) always stay home, for NPC runs. Only as many carriers go as the load needs, and they carry the food for the whole trip, there and back. A send to another lord's city is an ordinary transport, so what arrives is theirs.

sendtroopsGoal¶

Usage

sendtroops <to> <troop> <localAmount> <remoteAmount> [minBatch] [maxBatch] [/slots:N] [/maxdist:<tiles>]

Example

sendtroops Frontier a 20k 300k 10k 50k

Values

As sendresources, with a troop word in place of the resource: localAmount is how many this city keeps at home, remoteAmount how many a receiver is filled up to. There is no carrier, because the troops march themselves.

Default

/slots:1.

See also

keeptroops, requesttroops, recall

Works like sendresources, except the troops go as a reinforcement. A receiver's count is its troops at home plus reinforcements on their way. The city never sends below its own requesttroops level for that troop. One march carries at most the Rally Spot's limit.

Troops sent to your own city join it. Troops sent to another lord's city stay there as a garrison until you call them back (recall).

keepresourcesGoal¶

Usage

keepresources <to> <res:amount[,res:amount…]> [minBatch] [troopType] [/slots:N] [/maxdist:<tiles>]

Example

keepresources Capital f:1b,w:500m,s:500m,i:500m 50m

Values

res:amount: what this city keeps of each resource; the rest is sent. minBatch: the smallest send. troopType: the carrier, default transporters (when you write it, write minBatch before it). keepresource works as well.

See also

sendresources

A shorthand: each entry is read as its own sendresources line, with that amount as localAmount, remoteAmount *, the given minBatch and no maxBatch. The example is the same as four lines like sendresources Capital food 1b * 50m.

keeptroopsGoal¶

Usage

keeptroops <to> <troop:amount[,troop:amount…]> [minBatch] [/slots:N] [/maxdist:<tiles>]

Example

keeptroops Frontier a:50k,c:20k 5k

Values

troop:amount: how many of each this city keeps at home; the rest go. minBatch: the smallest send.

See also

sendtroops

Each entry is read as a sendtroops line with remoteAmount *. The example keeps 50,000 archers and 20,000 cavalry at home and sends every archer and cavalry above that to Frontier, at least 5,000 at a time.

config tradeConfig¶

Usage

config trade:<0|1>

Example

config trade:1

Values

1 the city trades; 0 it doesn't. Anything else is an error, and the city does not trade.

Default

0: no trading. tradepolicy and resourcelimits lines wait for it.

See also

tradepolicy, resourcelimits

Turns the trader on for the city. It needs a Marketplace. The Marketplace's level is how many market orders the city may have open at once (one per level), and that count includes orders you or a script placed. The trader works inside the city's schedulepolicy hours, reads the market at most once a minute, and places at most two trades a pass.

tradepolicyGoal¶

Usage

tradepolicy /type:<res> [/min:<amount|Nd>] [/max:<amount|Nd>] [/batch:<amount>] [/allowselltomin] [/donotautosellabovemax]

Example

tradepolicy /type:gold /min:2d

tradepolicy /type:food /min:1d /max:3d /batch:500k

tradepolicy /type:wood /min:5m /max:50m /batch:1m /allowselltomin

Values

Switch	Meaning
/type:	Required. food, wood (lumber), stone, iron or gold, or their letters.
/min:	Buy up to this. For gold it is the floor: no purchase ever takes the city's gold under it. Nd means N days: of troop food upkeep for food, of hero salaries for gold.
/max:	Sell what is above this. Food may use Nd too. Gold can't have a /max.
/batch:	The smallest trade worth making: the trader waits until it can buy or sell at least this much. Default 100k. Not on gold.
/allowselltomin	Written on the line of a resource that runs short. When there is no gold above the floor and nothing anywhere above its /max, sell the other resources down to their /min to buy this one.
/donotautosellabovemax	When every resource is at its /max, keep what this resource has above its /max instead of selling it for gold.

Default

The built-in values in the table above.

See also

config trade, resourcelimits

Write one line per resource. The two flag switches may also be written /allowselltomin:1 or :0, and = may stand for :. Two lines for the same resource add up, and the later line wins for a switch both set. A /min above its /max is an error. A line with an error is not used at all, and the city's engine notes say so.

Days are worked out from the city's current rates: /min:2d on food is 48 hours of what your troops eat. If the bot can't read the upkeep yet, it says so and leaves that limit out for the pass.

resourcelimitsGoal¶

Usage

resourcelimits <food> <lumber> <stone> <iron>

Example

resourcelimits 2b 50m 2b 20m

Values

Exactly four amounts, in that order.

See also

tradepolicy, config trade

A one-line way to hold each resource at one level: each amount becomes both the /min and the /max of that resource, so the city buys when under it and sells when over it. The gold floor becomes a day of hero salaries. One per city; if you write two, the later one wins.

Lines are read top to bottom. A tradepolicy line after resourcelimits changes what it names. One before it loses its /min and /max to resourcelimits but keeps its /batch and flags.

config hidingConfig¶

Usage

config hiding:<lead>

Example

config hiding:5 (5 minutes before the first attack lands)

config hiding:90s

Values

How long before the first attack lands the troops leave. A plain number is minutes (0.5 is 30 seconds); you can also write 30s, 2min or 1h. 0 turns it off.

Default

Off.

See also

hidingpolicy, config gate

When an attack whose landing the Beacon Tower shows is due within the lead, the city's troops leave. It is every troop at home, workers and transporters too, less what hidingpolicy /keep holds back.

With another city to go to. The troops go as a transport to your nearest city that has no attack on its way (or to hidingpolicy /target). They carry as much of the city's resources as they can hold: gold first, then food (after their own march food), iron, stone and wood. They leave the load in the safe city and camp, so they come home only after the last known wave has landed, plus /margin. A camp can be at most 24 hours, and the troops must carry the food for the march and the camp. Until both fit, the bot waits for the attack to come closer.

With no other city (a one-city lord). The troops go out on an attack with camp time, led by the lowest-level idle hero (never the keepatthome hero). It is aimed at the nearest level 1-2 NPC within 15 tiles that nobody holds and none of your marches is heading to. On Citavon a march waits out its camp time at home before it sets off, so the troops are out of the battle and a recall brings them back at once. The bot recalls the march once the waves have passed. If attacks are still coming when the march is about to set off, the bot recalls it 3 minutes before and sends a new one. If the bot were stopped and the recall never came, the troops would only meet a small NPC.

One march carries at most the Rally Spot's limit, so a big army leaves in several marches, one a pass, while there are free slots. The city needs a Rally Spot with a free slot, and enough food in the city for the trip.

hiding 5 written as a line of its own is read as config hiding:5, and the editor says so.

hidingpolicyGoal¶

Usage

hidingpolicy [/target:x,y] [/margin:<time>] [/keep:<troops>]

Example

hidingpolicy /target:210,377 /margin:5 /keep:a:5k,w:1000

Values

Switch	Meaning
/target:	The city to hide in, by x,y. It must be one of your own cities; any other place is refused and nothing hides. Without it: your nearest city with no attack on its way.
/margin:	How long after the last wave lands the troops stay away. Minutes, or 90s and the like. Default 2 minutes.
/keep:	Troops that stay home, e.g. a:5k,w:1000 (troop words as in requesttroops).

Default

Nearest safe city, 2 minutes, nothing kept.

Only used with config hiding. One per city. A /target city is used even when it is under attack itself.

config gateConfig¶

Usage

config gate:<lead>

Example

config gate:2

config gate:0.1 (6 seconds)

Values

How close an attack must be before it decides the gate: minutes, or 30s, 2min, 1h. 0 turns it off.

Default

Off: the bot never touches the gate. A gatepolicy line does nothing without it.

See also

gatepolicy

Each pass the bot looks at the attacks landing within the lead. An attack whose landing time is unknown (Beacon Tower under 3) counts as landing within it. From that it decides which situation the city is in, and opens or closes the gate as gatepolicy says. Without a gatepolicy line, every situation uses the bot's own choice.

gatepolicyGoal¶

Usage

gatepolicy <noattack> <regular> <scoutbomb> <mixed> <maintenance> [/mintoggle:<s>] [/junk:<troops>] [/defenceratio:<x>] [/strongarchers:<n>]

Example

gatepolicy 0 0 0 0 0 /junk:20k /defenceratio:3 /mintoggle:30

Values

The five numbers are the five situations, in this order. Each is 0 (the bot's choice), 1 (always open) or 2 (always closed). A missing number is 0.

Situation	When	The bot's choice (0)
noattack	No attack within the lead.	Closed: the troops stay behind the walls.
regular	Attacks within the lead.	Open if the wave is small (at most /junk), or if your troops at home are at least /defenceratio times the wave. Closed otherwise, and closed while the wave's size is unknown (Beacon Tower under 7).
scoutbomb	Only scouts within the lead.	Open if the city has at least /strongarchers archers, else closed.
mixed	Scouts and attacks together.	Closed.
maintenance	Accepted for NEAT files.	Never comes up: does nothing.

Switch	Meaning	Default
/junk:	A wave of at most this many troops is small enough to fight.	5,000
/defenceratio:	Fight when the troops at home are this many times the wave. /defenseratio works too.	5
/mintoggle:	The least time between two of the bot's gate changes. Seconds, or 1min.	10 seconds
/strongarchers:	Archers needed to open to scouts.	300,000
/weakarchers:, /loyaltyattack:, /scoutratio:	Accepted for NEAT files; they do nothing.	-

Default

gatepolicy 0 0 0 0 0: the bot's choice everywhere.

See also

config gate

"The wave" is every attack landing within the lead, added up. With Beacon Tower 7 each word counts as the top of its range, so the size is an upper bound. "Troops at home" counts every troop in the city except workers, so transporters and scouts count as well.

config gate:2
gatepolicy 0 0 0 0 0 /junk:20k /defenceratio:3 /mintoggle:30

defensepolicyGoal¶

Usage

defensepolicy [/junktroop:<troops>] [/usespeech:<loyalty>] [/usetruce:<loyalty>] [/usewarhorn] [/useivoryhorn] [/usecorselet] [/useultracorselet] [/usepenicillin]

Example

defensepolicy /junktroop:10k /usespeech:60 /usewarhorn /usecorselet /usepenicillin

Values

Switch	Uses	When
/junktroop:	-	An attack under this many troops is junk and is ignored. Only when the Beacon Tower counts the troops (level 7+); an attack it can't count is taken as real. Default 0: every attack is real.
/usespeech:	Rousing Speech	The city's loyalty is at or below this (0-100). Not while you are under a truce.
/usetruce:	Peace Treaty	The city's loyalty is at or below this, no army is marching on any of your cities, none of your armies is out, and your next truce is ready.
/usewarhorn	Battle Horn	A real attack is coming and no Battle Horn is running.
/useivoryhorn	Ivory Battle Horn	A real attack is coming and no Ivory Battle Horn is running.
/usecorselet	Mail Vest	A real attack is coming and no Mail Vest is running.
/useultracorselet	Plate Vest	A real attack is coming and no Plate Vest is running.
/usepenicillin	Field Hospital	A real attack is coming and no Field Hospital is running.

The on/off switches are on when written bare, or :1; :0 is off.

Default

No items used.

See also

config defensecooldown

The policy acts only while a real attack is on its way to this city, or in the cooldown after one (defensecooldown). The Rousing Speech is tried first, then the Peace Treaty, then the horns, vests and Field Hospital in the order above. The horns, vests and Field Hospital are only used while an attack is on its way, not in the cooldown.

The bot uses at most one item a pass, and only items you hold: it never buys one. An item that was tried, whether used or refused, isn't tried again for 5 minutes. Each switch is checked on its own, so with both /usewarhorn and /useivoryhorn on, both horns get used. Pick one horn and one vest.

config defensecooldownConfig¶

Usage

config defensecooldown:<minutes>

Example

config defensecooldown:60

Default

30 minutes.

See also

defensepolicy

How long after the last attack landed the city still counts as "just hit", for defensepolicy's Rousing Speech and Peace Treaty and for reservedbarrack. The landing time is only recorded while config hiding is on, for attacks whose landing the Beacon Tower shows. Without config hiding this setting has no effect.

config warrulesConfig¶

Usage

config warrules:<minutes>

Example

config warrules:5

Values

Minutes between updates (30s and the like work too). 0: off.

Default

Off.

See also

config attackgap

Posts the city's attacks in alliance chat. The first post goes out as soon as an attack is seen. After that, a new post goes out every X minutes while the picture changes (a new attack, or a landing time that moves), and a reminder every 5 × X minutes while it doesn't. A post reads like [war] Rome (210,377): 3 incoming in 2 wave(s), first in 4m 10s — Bob (Wolves) from Den (12,34) · 2,500 archer. It holds only what the Beacon Tower shows. A lord with no alliance is told so in the engine notes, and nothing is posted.

config attackgapConfig¶

Usage

config attackgap:<seconds>

Example

config attackgap:10

Default

6 seconds.

Attacks landing at most this many seconds apart count as one wave. On Citavon Bot this only changes how many waves the warrules post counts. The gate and hiding look at every attack on its own.

config embassyConfig¶

Usage

config embassy:<0|1|2>

Example

config embassy:2

Values

1 let allied troops stay in the city; 2 keep them out; 0 leave the setting as it is.

Default

0.

Keeps the city's Embassy setting where you want it, putting it back on every pass if it is changed. It needs an Embassy in the city.

config nohealingConfig¶

Usage

config nohealing:<0|1>

Example

config nohealing:1

Default

0: the bot heals.

Without this setting the bot heals every wounded troop in the city as soon as the city has the gold for it, on every pass, around the clock. You don't need any other goal for that. config nohealing:1 leaves the wounded alone, so you can heal them yourself or keep the gold.

config keepatthomeConfig¶

Usage

config keepatthome:<0|1>

Example

config keepatthome:1

Default

0.

The city's hero with the highest attack (a captured hero doesn't count) stays home. NPC farming, valley runs and buildnpc marches never take it, and hiding never sends it out to lead the troops away. Scripts can still send it.

config monitorarmyConfig¶

Usage

config monitorarmy:<n>

Example

config monitorarmy:1

Does nothing. It is accepted so that a NEAT goal file reads without an error. It never did anything on NEAT either, so the editor shows the line as fine, and the engine notes say it does nothing.

config wartownConfig¶

Usage

config wartown:<0|1|2>

Example

config wartown:1

Values

Value	Meaning
0	Off.
1	On. The training hero may still come and go.
2	On, and the training hero stays in the city it is in now.

Default

0.

See also

wartownpolicy

While War Town Mode is on:

• No NPC farming, valley or buildnpc march leaves the city.
• Its push lines (sendresources, keepresources and so on) wait, and other cities' request lines don't draw from it.
• When the mode turns on, the city's marches that are still on their way out are recalled, once. Marches already coming back and garrisons in other places are left alone.
• The city still receives: other cities may send to it, and its own request lines still pull.

It doesn't hold hiding, which still sends the troops away from an attack, and it doesn't hold your scripts.

wartownpolicyGoal¶

Usage

wartownpolicy <start> <end> [<start> <end> …]

Example

wartownpolicy 22:00 07:00

wartownpolicy 06:00 08:00 18:00 23:30

Values

Pairs of times, hh:mm, 24-hour clock. A window may run past midnight. 24:00 may end one.

Default

None: config wartown holds all day.

See also

config wartown, schedulepolicy

Limits config wartown to these hours. Outside every window the city acts as if config wartown:0. The times are on the clock of the computer the bot runs on, not the game's clock. Each window starts at its start time and ends just before its end time. One per city. It doesn't limit the console's switch: Off and the On choices hold at any time.

Each time the mode turns on, as a window opens, the city's outgoing marches are recalled once, as with the config line.

labelScript¶

Usage

label <name>

Example

label trainarchers

Values

name: one word of letters, digits and _ $ . ! -; any case (Top and top are the same label).

See also

goto, gosub, loop, autorun

Marks a place in the script for goto, gosub, loop and the Run box's start point to jump to. It does nothing when the run passes over it. Two labels with the same name are an error. A label cannot sit behind an if. A label inside a function belongs to that function: you cannot jump to it from outside, nor out of the function to a label outside.

The label autorun is special: autorun starts a loadout from it (Autorun).

gotoScript¶

Usage

goto <label>

Example

if $error goto retry

See also

label, gosub, ifgoto

Carries on from the line of that label. A label that does not exist is an error before the script starts. Use it with if for choices and with a label above it for loops.

gosubScript¶

Usage

gosub <label>

Example

if city.resource.food < 1m gosub buyfood

See also

return, ifgosub, function

Jumps to the label like goto, but remembers where it came from: the next return brings the run back to the line after the gosub. Subroutines may call other subroutines, up to 1,000 deep. A gosub to a label with no return anywhere after it gets a warning (it still runs).

Keep subroutines below an end, so the run does not walk into them by itself:

gosub report
train a:1k
end
label report
echo city.name "has" city.troop.archer "archers"
return

returnScript¶

Usage

return [expression]

also written gosubreturn

Example

return

return total * 2

See also

gosub, function, call

What it does depends on where the run is:

• after a gosub: back to the line after that gosub (a value is ignored);
• in a function: the function ends and gives the value (or undefined);
• at the top level of a script run with call: back to the calling script, the value in its $result;
• at the top level of the script you ran: the script ends.

ifScript¶

Usage

if (<condition>) <any line>

Example

if city.troop.archer < 20k goto trainarchers

if $error == null echo "it worked"

if a == 1 if b == 1 echo "both"

if x > 5 item = "big"

See also

Expressions, ifgoto, repeat

Works out the condition; when it is true the rest of the line runs, otherwise the run goes on with the next line. The brackets are optional: as much of the text after if as reads as one expression is the condition, and the rest is the line. That line can be anything (a command, goto, an assignment, another if …) except label, function, endfunction and endloop.

False are false, 0, "" (empty text), null, undefined and NaN; everything else is true, including the text "0" and an empty list. Inside a condition a single = compares, as == does.

There is no else. Jump over the other branch with a label, or pick a value with ?::

if city.resource.food > 5m goto rich
echo "poor"
goto after
label rich
echo "rich"
label after
mood = city.resource.food > 5m ? "rich" : "poor"

An if in front of repeat is checked again before each round: if !x repeat keeps going only while x stays false.

ifgotoScript¶

Usage

ifgoto (<condition>) <label>

Example

ifgoto (city.troop.archer < 5000) more

See also

if, goto

An older form of if (condition) goto label, kept so old scripts run. It does the same.

ifgosubScript¶

Usage

ifgosub (<condition>) <label>

Example

ifgosub (city.hasEnemyArmies) warn

See also

if, gosub

An older form of if (condition) gosub label. It does the same.

loopScript¶

Usage

loop [count] [label]

loop <count> … endloop

Example

loop

loop 5 farm

Values

Form	What it does
loop, loop 0	Back to the top of the script, forever (until Stop).
loop 5	The whole script runs 5 times in all, then the run goes on below.
loop name	Back to label name, forever.
loop 5 name, loop name 5	The part from label name runs 5 times in all.
loop 3 … endloop	The lines between run 3 times; without a count, forever. Blocks may sit inside each other.

See also

endloop, repeat, goto

A loop line without a label that an endloop further down closes starts a block; otherwise it jumps back. Counts are "in all": loop 5 at the bottom of a script makes it run five times, not six. When the count is used up the loop forgets it, so reaching the same loop again later counts afresh.

Inside a function, loop without a label goes back to the function's first line, not the script's. In a dry run a forever loop does not go round: it says what it would do and the run goes on.

loop 5
  scout 312,145 none s:1
  sleep 60
endloop

endloopScript¶

Usage

endloop

See also

loop

Closes the nearest open loop block above it: the run goes back to the line after that loop until its count is used up. An endloop with no loop to close is an error. It cannot sit behind an if; to leave a block early, goto a label below it.

repeatScript¶

Usage

repeat <count>

repeat or repeat 0

Example

train a:250 then repeat 4 — four batches of 250 archers

sell wood 1000 @0.55 then repeat

Values

count: how many times the line runs in all, counting the run just before: repeat 1 adds nothing, repeat 4 adds three more. No count, or 0: again and again until that line fails or you press Stop.

See also

loop, if

Runs again the last line that did something: a command, echo, print, sleep, an assignment or expression line, call, callfunc, command or a goal line. That is the last such line in time, not the line written above: after a gosub it is the last one the subroutine ran. Each round shows in the output as (run 2 of 4), or (repeat 3, until it fails or Stop).

• A counted repeat runs every round whatever each one gets back. A repeat without a count waits 0.2 seconds between rounds and stops at the first round that fails (repeat ends — line N did not go through).
• Behind an if, the condition is checked again before every round after the first, and the repeat ends when it no longer holds.
• A repeat with nothing run before it, or right after a repeat that never ends, is an error. A repeat without a count is refused after buyitem: it would keep spending until it failed.
• In a dry run a repeat without a count is skipped with a note; counted rounds run.

sleepScript¶

Usage

sleep <seconds | m:ss | h:mm:ss | @:hh:mm[:ss[.ms]] | rnd:max | rnd:min:max>

Example

sleep 5

sleep 1:30 — a minute and a half

sleep 1:00:00 — an hour

sleep @:14:15 — until 14:15

sleep rnd:300:600 — 5 to 10 minutes, at random

Values

Form	Wait
5, 0.5	that many seconds (fractions allowed)
1:30	minutes and seconds (the seconds always two digits)
1:00:00	hours, minutes and seconds
@:14:15, @:14:15:30, @:14:15:30.500	until that time of day, on a 24-hour clock; if it has passed today, until tomorrow
rnd:300	a random time from 0 to 300 seconds
rnd:300:600	a random time from 300 to 600 seconds (the second number may not be the smaller)

Pauses the script. Stop ends a sleep within a quarter of a second. The output shows the wait: for @: the time it waits for, for rnd: the time it drew.

sleep takes no expressions. To wait for a worked-out time, use a variable in percent signs (sleep %wait%, where wait = 30 * 60) or execute (execute "sleep " + wait). A dry run sleeps too.

echoScript¶

Usage

echo <expression> [expression …]

Example

echo "My city is at " + city.coords + " with" city.troop.lightCavalry "cavalry"

echo "Food in an hour: {city.resource.food + city.resource.food.increaseRate}"

See also

print, Text

Writes to the Output tab. Expressions side by side, separated by spaces, are each worked out and joined with one space. A bare word that nothing defines prints as written, so echo done now prints done now. Text with several lines prints as several lines.

• If the line does not read as expressions side by side, it prints exactly as written. A comma between items does that: echo a, b prints a, b. Write echo a b.
• A quote left open at the end of the line closes there.
• A - between two items subtracts: echo 5 -3 prints 2. Put text in quotes.
• A bare word that happens to be a known name prints that thing, not the word. Names are read in any case, so echo number, echo max or echo date print function Function() {}. Put words in quotes when in doubt.

echo does not change $result or $error.

printScript¶

Usage

print <text>

Example

print Sending to %target% now

See also

echo

Writes the rest of the line to the Output tab exactly as written. Only %name% replacement variables are filled in; quotes, {…} and names stay as they are.

setScript¶

Usage

set <name> <value>

Example

set target 312,145 then attack %target% any a:5k

Values

name: letters, digits and _, not starting with a digit; any case. value: the rest of the line, as plain text.

See also

Variables, assignment

Makes a replacement variable: from then on, %name% anywhere in a line (even inside quotes) is swapped for that text before the line is read. Set it again to change it; lines below use the new text when they run, so it can change inside a loop. The value is never worked out: set n 2+2 makes %n% the text 2+2. A %name% in the value is filled in when the set line runs.

A %name% that no set makes and no assignment gives a value is an error before the script starts: %x% is not set — put set x <value> above this line. Replacement variables are not handed to a script you call.

name = valueScript¶

Usage

<name> = <expression>

<name> += | -= | *= | /= | %= <expression>

<name>++, <name>--, ++<name>, --<name>

<object>.<key> = …, <list>[<index>] = …

Example

waves = 0

waves += 2

plan.target = "312,145"

list[0] = "first"

See also

Variables, Expressions