Command-line Features

Basic Commands

  • alias - Generate a definition for a simple alias
  • burst - Send commands unsynchronized
  • coordinate - Translate coordinates
  • danno - Dump all announcements
  • dtele - Dump all telegrams
  • execute - Send the content of a file to the empire server.
  • ltest - Compute the mobility needed to move a land unit.
  • null - Run command with no output
  • origin - Block unsupported command
  • projection - Show commodities needed to build new units
  • raw - Send a command without client interpretation
  • rdb - Refresh client databases
  • remove - Remove foreign units from the database.
  • runfeed - Send the output of a system command to the empire server.

Tk Windows Commands

  • cshow - Hack for show command.
  • Disp - Highlight specified sector on main map using a color gradient
  • Login - Re-open the login window
  • Map - Open an additional graphical map window
  • Sect - Highlight specified sectors on main map
  • wind - Output command to a new Tk Window
  • wread - Graphical correspondence tool

Information Commands

  • define - List all online commands
  • out - Debugging tool - dumps database

Smart Commands

  • dmove - Move commodity around up to distribution thresholds
  • eval - Evaluate an expression for a sector
  • foreach - Run given command on specified sectors
  • mmove - This command produces a best-path multimove
  • Mover - Issue a multi-stage move
  • nova - Explore adjacent wilderness sectors
  • Predict - Get predictions for a sector
  • setfood - set food thresholds

This file is intended to give a brief summary of the "smart" commands available in the Python/Tk empire client.

Each of the following commands may be entered as if they were a normal empire server command. The client will automatically recognize these commands and handle them locally, where applicable.

In addition to commands that are typed in on the command line, commands can also be specified in three built-in configuration files. The file, "first.emp" is executed the first time the client connects to the server, "start.emp" is run every time the client starts up, and the file "connect.emp" is run each time a connection is made to the server.

Important Change! Previous versions of the client had a command known as "sync". This command has be renamed to "rdb", and its syntax has been altered!


Basic Commands

Command rdb

Syntax

rdb

Description

This command is used to keep the sector/ship/plane/nuke/etc databases synchronized. When this command is issued dump/sdump/pdump/ldump/lost commands will be buffered to the server. Empire 4.x timestamps are used to ensure only recently updated values are returned. It is a good idea to use this command instead of manually running dump yourself.

At one time, the server had a bug that caused empire updates to modify sectors and units without updating the timestamps. To circumvent this problem, 'rdb' was expanded to use the form 'rerdb'. A "re-refresh" will force this command to ignore timestamps and dump the entire database. It should not be necessary to use this form of the command.

Additionally, the command rdb (or rerdb) may contain a suffix that contains any combination of 'epslno'. 'e' stands for sector dump, 'p' is a plane dump, 's' is a ship dump, 'l' is a land dump, 'n' is a nuke dump, and 'o' is a lost dump. When these selectors are specified, only the corresponding dumps will be sent. This is useful when it is known which databases have changed, and it is not desirable to dump all the databases. For example, you might specify 'rdbel' to synchronize just sectors and land units.

During processing of the outgoing command queue, if two or more rdb commands are buffered simultaneously, the client will automatically ignore the first database refresh. Since the first refresh is contained entirely within the second, it doesn't make much sense to send the first. When this behavior is not desired, the rdb command can be suffixed with a "P" flag. This prevents the first rdb command from being ignored.

Command null

Syntax

null <cmd>

Description

Send <cmd> to server, but don't display its output on the command-line. The output will still be parsed by the internal parsers. For example, "null map *" will update the graphical display without flooding the output window.

Multi Command Line

Syntax

<cmd1> ; <cmd2>

Description

This command allows multiple commands to be sent on the same line. For example, "map * ; bmap *" will send "map *" followed by "bmap *".

Redirections

These commands redirect the output of an empire command.

<cmd> | <program>

Send output of <cmd> to the system command <program>

<cmd> > <file>

Store output of <cmd> in new file called <file>

<cmd> >! <file>

Store output of <cmd> in file named <file>, overwriting an existing file if any.

<cmd> >> <file>

Store output of <cmd> at the end of the file <file>

Commands execute & runfeed

Syntax

execute <file>
runfeed <program>

These commands allow server commands to be collected in an external source. When processing the commands, lines beginning with a "#" are considered comments and are silently ignored. All other lines are interpreted as client or server commands.

The "execute" command may be abbreviated to as short as "exe". This command is intended to mimic the effects of the similar server based command.

Command alias

Syntax

alias <cmd> <newcmd>

All future invocations of <cmd> will automagically be altered to send <newcmd> instead. Optionally, the alias may contain special substitution characters. When evaluating, the sequence $* is substituted with the command's arguments, $X is substituted for the Xth word of the command's arguments ($0 will be replaced by the command name), and $$ is replaced by a single $ character. For example, the command "alias mvoe move $*", makes mvoe function exactly like move.

To make an alias permanent, place the alias command in the start.emp file. There are also many examples of aliases in this file.

Note: There is no protection from infinitely recursing aliases. If an alias calls itself it will probably end up hanging the client!

Note2: When in burst mode aliases may also be evaluated for sub-prompts. Because of this, it is a good idea to plan out aliases that don't easily conflict with common empire sub-prompts.

Command burst

burst <cmd>

The burst command can be used to send a series of commands to the server without synchronizing the output. Synchronizing output can incur a significant amount of latency. By "bursting" multiple commands simultaneously, a significant improvement can be made to the overall connection speed. Unfortunately, when multiple commands are "bursted", it becomes possible for a command to accidently answer the preceding command's sub-prompt. This utility is most powerful when it is applied to commands whose sub-prompts (or lack of sub-prompts) can be entirely predicted.

Note: The internal parser will parse bursted commands!

Simple examples:

burst tele 4;Hi there.;What's up?;.
This command will burst the 4 lines of data ('tele 4', 'Hi there.', 'What's up?', and '.'). Because telegram has predictable sub-prompts, it is safe to assume that the above will tele 4 with the included message.
burst nation;version;update;map *
This command will send the four specified commands simultaneously. Because nation, version, and update never take sub-prompts, and because map has a predictable sub-prompt - It is safe to assume that these commands will execute properly.

For a more in depth analysis, see the burst section in the TIPS file. There are also a number of examples in the default start.emp file.

Command coordinate

Syntax

coordinate [-]<country number> <your coordinate> [<their coordinate>] 

Description

The coordinate command can be used to set a countries coordinates that can be used to translate from your coordinates to theirs. Also it will translate from theirs to yours by using a '-' (minus sign) in front of the country number. Setup the translation by entering
coordinate <country number> <your coordinates> <their coordinates>
Translate from yours to theirs by entering
coordinate <country number> <your coordinates>
it will display country number and the coordinates translated into theirs. Translate from theirs to yours by entering
coordinate -<country number> <their coordinates>
It will display the country number and the coordinates translated into yours.

Command origin

Syntax

origin

Description

Block unsupported server command.

The server origin command is not supported by the client. To prevent accidental error, this command will be blocked before transmission to the server. Please see the origin section of the TIPS.html file for more information.

Command raw

Syntax

raw <cmd>

Normally, all commands typed in are checked for client synthetic commands and aliases. The raw command can be used to prevent this check. When using this command, everything following "raw" will be sent to the server completely unmodified.

Note: The client will still parse the output from commands that are sent raw!

WARNING! In raw mode, it is possible to send the command "exec" to the server. The client does not support the server's exec protocols. If exec is sent in raw mode, it may become necessary to disconnect via the Login Window to reset the client's connection.

Command remove

Syntax

remove (l|s|p) <sects>

Description

Sometimes foreign units are still present in the database while they're not visible anymore or have been destroyed. The "remove" command allows the user to remove such units. Example:

remove s * will remove all foreign ships from the database.

remove l #1 will remove all land units from realm 1.

Command dtele

Syntax

dtele

Description

All telegrams sent or received are copied to the screen or can be redirected to a file with the usual rediction operators.

dtele >! tele.txt will send all telegrams to the file 'tele.txt'.

Command danno

Syntax

danno

Description

All announcements sent or received are copied to the screen or can be redirected to a file with the usual rediction operators.

danno >! anno.txt will send all announcements to the file 'anno.txt'.

Command projection

Syntax

projection

Description

This command tells you if one or more of your sectors needs more commodity, availibility to build all your units (ships, planes and land units). You need to have issued a 'show ship|plane|land build' before.

Some examples:

[71:640] Command : projection
Building Projections
====================
[71:640] Command : 

It seems that you're not building anything this update!

[72:637] Command : projection
Building Projections
====================
You should issue a 'show plane build' command to update the database
[72:637] Command : 

The type of planes you're building isn't present in your database: You've never issued a 'show plane build' or maybe you did but so long ago that this new plane type didn't exist at that time. You must send a 'show plane build' to get all plane types.

[75:636] Command : projection
Building Projections
====================
Sector 6,2 is ok.
[75:636] Command : 

Sector 6,2 has all needed commodity to build your units.

75:635] Command : projection
Building Projections
====================
Sector 7,-1 needs 59 more lcm
Sector 7,-1 needs 5 more mil
Sector 6,2 is ok.
[75:635] Command : 

Sector 7,-1 (an airport) needs 59 more lcms and 5 more mils to make all the planes located there 100%.

Command ltest

Syntax

ltest <unit ID> <sector>

Description

The ltest command behaves just like the test except that it applies to a land unit as shown in the example:

[133:630] Command : ltest 329 -5,-5 
Looking for best path to -5,-5
Using best path 'yyyyygy', movement cost 1.601
Total movement cost cost: 80, new mob: 47

Tk Window Commands

What follows is a quick summary of the Tk based commands. Many of these commands are further documented in the gui.html file.

Command wind

Syntax

wind <cmd>

Description

Send <cmd> to server, pop-up a new window on the desktop, and redirect all output from the command to this window. For example, the command "wind info Products" would send that 20 page manual to its own window with its own scrollbar. This window can then be left up for future reference; it will not interfere with sending and receiving of additional empire commands. An unlimited number of these output windows may be used simultaneously.

Command wread

Syntax

wread

Description

The internal parsers automatically store incoming telegrams, incoming announcements, and outgoing telegrams. Sending this command will pop up a graphical telegram window which allows reviewing and responding to these messages.

Note: If you are short on disk space, you may have to use this tool to delete old telegrams and announcements from the database. Since the client automatically stores old messages, the database can become rather large over time.

Command Map

Syntax

Map

Description

This command will pop up an additional graphical map in its own desktop window. An unlimited number of these map windows may be used simultaneously, and each map window can have its own origin and scale.

Command cshow

Syntax

cshow <'ship'|'land'|'plane'>

Description

This command will send "show X build; show X cap; show X sta" and rearrange the output into multiple columns. A Tk window will pop up with the resulting formatted display.

Command Login

Syntax

Login

Description

This command forces the Tk interface to re-open the Login window. When connected to a server, the login window may be used to force a disconnect. When not connected to a server, the Login window can be used to alter database, server, and country information.

Command Sect

Syntax

Sect <sectors> [<selectors>]

Description

This command locally emulates the empire server's sect command. It can be used to mark sectors on the graphical map that meet a provided empire selector. It is intended to work similar to the server based "sect" command.

Note: This command uses the internal database to determine which sectors apply. If the database is not synchronized, the results will not be correct!

The arguments to sect work in the same manner as the foreach command which is described below.

Optionally, you may run the Sect command with no arguments at all to erase the highlights from any past Sect commands.

Command Disp

Syntax

Disp <commodity> <sectors> [<selectors>] [min <min value>] [max <max value>]

Description

This commands highlights selected sectors using a color gradient depending on the level of the commodity specified. If the <min value> is set all levels below it are seen as if they were egal to this <min value>. The same applies for the <max value>.

Like the Sect command, Disp uses the internal database.

You may run the Disp command without any arguments to erase the highlights from any past Disp commands.

Smart Commands

Command eval

Syntax

eval nation|version|<sect> <cmd>

Description

This command allows a command to contain python expressions that are evaluated using the nation database, the version database, or a sector database.

Note: This command uses the internal database. If the database is not synchronized, the results will not be correct!

<sect> is a sector designation of the form x,y. (Note, if you wish to run a programmable-command on many sectors, use the foreach command.) This sector's database is referenced when evaluation the rest of the command.

<cmd> is an empire command that contains an arbitrary number of python expressions embedded within it. The python expressions must be enclosed within [ and ] characters (the square brackets). These python expressions are evaluated using a namespace from the specified database. The names of the variables are the same as their corresponding empire selectors, and similar to the empire selectors they may be abbreviated (for example, both 'newdes' and 'new' are equivalent). In addition to the standard empire selectors, there are two included aliases: sect (A string containing the sector's x,y pair), and dist (A string containing the dist_x,dist_y pair). See the selectors section of the TIPS file for more information.

An example:

eval 0,0 move mil [dist] [mob/2+1-mil] [sect] ; anti [sect]
In this example, enough mil is pulled in from sector 0,0's dist center so that the maximum number of mil usable in an anti command is available. The anti command is then executed.

Command foreach

Syntax

foreach <sectors> [<selectors>] <cmd> 

Description

Similar to the PEI foreach command, this command takes a sector range, an optional ?<var>=<val>&... selector, and then runs cmd on each sector that meets the requirements.

Note: This command uses the internal database. If the database is not synchronized, the results will not be correct!

<sectors> and <selectors> are similar to those on the empire server. <sectors> can be a range of sectors (x1:x2,y1:y2), an '*' to specify all sectors, or an empire range of the form '#X'. <selectors> is a series of variable conditions that may be specified using the form "?<var><cond><var>" where <var> is a either a constant or a valid empire variable, and cond is one of '=', '<', '>' or '#'. Any number of selectors may be specified by appending them with a '&' character in-between. See the empire selectors section of the TIPS.html file for advanced information.

<cmd> is a string that will be parsed in the same manner as the eval command.

An example:

foreach * ?dust=1&d_dist=0 move d [sect] 1 4,7
The above command moves 1 dust to sector 4,7 from all sectors that have exactly 1 dust and have no dust threshold.

A more complex example:

foreach * ?mil<50 move mil [dist] [50-mil] [sect]
The above attempts to resupply all sectors from their respective dist centers so that all sectors have a minimum of 50 mil.

An insane example:

foreach * move gun [10>gun and dist+' '+`10-gun`+' '+sect or sect+' '+`gun-10`+' '+dist]
The above moves guns around so that exactly 10 guns are in every sector. Sectors that have more than 10 guns in them move guns to their dist centers; sectors with less than 10 guns move guns from their dist sectors.

Command nova

Syntax

nova <civ|mil> <start sector> [<to sector>]

Description

The start sector has to be an owned sector that contains mobility and civs/mil. If [to sector] is specified, it must be an owned sector that is adjacent to unowned wilderness. (If [to sector] is not specified then start sector must be adjacent to unowned wilderness.) Explore commands are then generated from the start sector to all adjacent wilderness sectors. No best path is calculated.

Warning: This command is experimental! Do not use it in important situations. (But it might be useful in blitzes.) It uses the internal database, which has to be synchronized.

Command mmove

Syntax

mmove <commodity> <source sectors> <min level> <mobility> <dest sectors> <max level>

Description

Invoking mmove will generate a series of commands that attempt to move the commodity specified by <commodity> from the sectors in <source sectors> so that there is <max level> of the commodity in all the sectors in <dest sectors> such that all source sectors will not go below <min level> of the commodity and not go below <mobility> mobility.. Phew..

Ok, an example:

mmove food * 60 40 * 60
This moves food from sectors with more than 60 food to sectors with less than 60 food. At least 40 mobility will be left in every sector.

mmove civ #1 768 80 #2 ?new#+ 768
This will attempt to move civs from sectors in realm 1 that have more than 768 civs to sectors in realm 2 that have less than 768 civs and are not road sectors. At least 80 mobility is left in each sector.

The mmove utility is a contribution from Ulf Larsson. Warning! This code is still experimental! Please use with discretion.

Command dmove

Syntax

dmove <commodity> <source sectors> <mobility> [zero] [<dest sectors>]

Description

The dmove command behaves like mmove except that the commodity levels used are the distribution thresholds. Unless the zero argument is provided, a sector with no commodity threshold (i.e. a threshold equal to zero) won't be included in the source sectors. The difference between this command and mmove is that each sector can have a different min level or max level.

Examples

dmove i * 67
This command will generate a list of move commands from sectors where the stock of iron is above the iron threshold (and where the iron threshold is greater of equal to one) to sectors where the stock of iron is below the iron threshold. The amount of iron in source sectors won't go below their iron thresholds and in destination sectors it won't go above their thresholds.
thr d * ?dust=1&gold=0 0
rdb
dmove d * 67 zero
The first command sets the threshold of sectors that used to be gold mine where 1 dust is remaining to 0. The second refreshes the database. Finally, the third one will move commodity from these sectors to those where dust level is below thresholds (for instance banks, tech centers).

Command Mover

Syntax

Mover <commodity> <amount> <sector list>

Description

The Mover utility moves amount of commodity from the first sector of sector list to the second sector of sector list, to the third sector, fourth sector, and so on until the commodity resides in the last sector of sector list . The purpose of this utility is to move commodities around using way-points as mobility sinks.

The amount field has a special meaning in this utility:

Note: This command is still in its infancy. Both it and the graphical move utility, which uses this command, should be used with a little caution. Also, this command has no support for moves that cause enemy interdiction. If interdiction occurs, it will probably not do what you want.

Command Predict

Syntax

Predict <sector>

Description

This command displays information about the effects of an update on a sector. On a graphical interface, this output is also available in the Sector Census Window. Currently, it supports population growth statistics, starvation warnings, worker information, and new efficiency data.

Command setfood

Syntax

setfood <sector list> [no] [force]

Description

This command computes for each sector in <sector list> the amount of food needed for full growth and sets the food threshold depending of the options provided.

If no options are provided (e.g. setfood *), the thresholds calculated are sent to the server only if they are above current thresholds. For instance, if a sector needs 35 food and already has a food threshold of 60, no command is sent for this sector.

If the force option if present (e.g. setfood * force), the calculated thresholds replace current ones even when they are inferior to them.

If the no option is present (e.g. setfood * no), the calculated thresholds replace those present in the internal database but aren't sent to the server.

Note: A threshold command uses one BTU. As a threshold command is sent to the server for each sector in the list, you may consume a lot of BTUs when using this command for a large area.

Note 2: The purpose of the options no and force is to allow the use of the dmove command to move food to sectors that need it without spending hundreds of BTUs in the process.

Note 3: When using the no option, the internal database gets out of sync with the game. You should issue a null dump * f_dist command just after to resync food threshods.

Examples

rdb
setfood * no
dmove f * 67
null dump * f_dist
First, we sync the database, Second, we set food thresholds in the internal database. Then the dmove command moves food around to where it is needed. As the internal database is out of sync (at least regarding food thresholds), we force a resync with the last command. This serie of commands could be turned in to a single command with the alias command:
alias lsetfood rdb;setfood $* no;dmove f $* 67;null dump $* f_dist

Information Commands

Command define

Syntax

define

Description

You may obtain a list of all client commands that are currently available by sending the command "define".

Command out

Syntax

out

Description

Don't run this - it is only useful for debugging. (And not very useful at that.) It will send the entire database to the empire console.