1 This file contains material useful for client writers.
6 The protocol between Empire client and server is plain text. It is
7 simple enough that you could play using nothing more than telnet.
10 A session uses either ASCII or UTF-8, controlled by session option
11 utf-8. See below for session options. The session always starts in
14 Client-server communication is line-oriented.
16 The server sends lines of output. Each output line starts with an
17 identification string, followed by a space, then arbitrary text, then
20 Identification strings encode small integers called output ids as base
21 36 numbers. Characters '0' to '9' represent digits 0 to 9, and 'a' to
22 'z' represent 10..35, as do 'A' to 'Z'. Symbolic names for ids are
25 empire-client versions before version 4.3.11 parse large output ids
26 incorrectly. Such ids do not currently occur.
28 Clients shall be able to safely handle output lines of arbitrary
29 length. Naturally, a client may not be able to handle a sufficiently
30 large line without loss of functionality, but safety must be ensured.
32 When using ASCII, the most significant bit in text characters
33 indicates highlighting.
35 The following control characters have a defined meaning:
37 ASCII name decimal meaning
38 ----------------------------------------------------
39 horizontal tab 9 move to next tab stop(1)
40 line feed 10 end of line
41 shift out 14 begin highlighting(2)
42 shift in 15 end highlighting(2)
44 (1) Tab stops are every eight columns.
45 (2) Only if session uses UTF-8
47 Other ASCII control characters should not occur and may be ignored by
48 clients. Likewise, overlong or malformed UTF-8 sequences should not
49 occur and may be ignored.
51 The server prompts for input. Each prompt `consumes' one line of
52 input (except for C_EXECUTE, and when a command is aborted, as
53 described below). Input lines are arbitrary text, terminated by line
54 feed, which is optionally preceded by carriage return (decimal 13).
55 Lines should not contain ASCII control characters other than
56 horizontal tab. Clients should not send overlong or malformed UTF-8
59 A client is called synchronous if it waits for a prompt before it
60 sends another line of input. Else it is called asynchronous.
62 Asynchronous clients must take care to avoid blocking on sending
63 input. If the client process blocks that way, it can't receive server
64 output until the server reads more input. That may never happen,
65 because the server may well block on output, which then deadlocks the
68 An Empire session consists of three phases: login, playing, and
69 shutdown. empire-client is synchronous in the login phase, and
70 asynchronous afterwards. Versions before 4.3.11 could deadlock as
76 In the login phase, the server prompts for login commands.
78 The server starts with a C_INIT prompt. The login phase ends when the
79 server sends another C_INIT prompt, which starts the playing phase, or
80 when it enters the shutdown phase, as described below
82 The server replies to a login command with another prompt. Except as
83 noted below, the server replies C_BADCMD for syntax errors, C_CMDERR
84 for other errors, and C_CMDOK on success. In any case, the prompt
85 text contains further information intended for humans.
91 Identify the client. This is optional. If given, version
92 information should be included.
96 Set country name to COUNTRY.
100 If another connection for this country is in the playing phase,
101 force it into the shutdown phase, else do nothing. Country must be
104 Reply is C_EXIT regardless of success.
106 * options OPTION[=VALUE]...
108 Negotiate session options. Each argument requests setting OPTION to
109 VALUE. The string VALUE is interpreted in an option-specific way.
110 The form without the `=' sets it to an option-specific implied
113 The server accepts the request by sending C_CMDOK. If the server
114 encounters an unknown option, it rejects the request by sending
115 C_BADCMD. It rejects unsupported values by sending C_CMDERR. It
116 may or may not process valid parts of rejected requests.
118 If there are no arguments, the server lists its options. For each
119 option, it sends a C_DATA line with OPTION=VALUE as text, and
120 finally a C_CMDOK. If it supports no options at all, it may reply
121 with C_BADCMD instead.
123 See below for supported session options.
127 Authenticate. Country name must be set already.
129 * play [USER COUNTRY PASSWORD]
133 If no arguments are given, the country must be authenticated
136 Else, argument USER sets the user name, COUNTRY sets the country
137 name, and PASSWORD authenticates.
139 Some error conditions result in a C_EXIT reply. Clients should
140 treat it just like C_CMDERR.
142 On success, the server sends C_INIT. The text is the protocol
143 version number in decimal, currently 2. The client should terminate
144 on protocol versions it doesn't know how to handle.
146 The protocol version is not expected to change often. In fact, it
147 hasn't changed since the oldest known versions of Empire.
149 Unlike the first C_INIT, the second one is not a prompt, i.e the
150 server does not consume a line of input for it.
152 The session then proceeds to the playing phase.
156 Terminate the session. The server replies with C_EXIT and enters
161 List all countries that are still in sanctuary. The output consists
162 of a number of C_DATA lines with human-readable text.
164 This command is only recognized if option BLITZ is enabled.
168 Set the user name. This is optional and defaults to "".
170 If the login phase takes more than login_grace_time (default 120s),
171 the server enters the shutdown phase.
176 In the playing phase, the server sends data, control and prompt lines.
178 Clients signal `EOF' by sending a line "ctld\n", and `interrupt' by
179 sending "aborted\n". The server treats these conditions specially, as
180 described below. Anything else is either a command or input for a
181 command, depending on how the server prompts for the line.
183 empire-client signals `EOF' when it encounters an end-of-file
184 condition while reading player input. It signals `interrupt' when it
185 catches SIGINT, which is normally triggered by Ctrl-C.
187 The following ids occur:
189 * Command prompt C_PROMPT
191 The server consumes a line of input. On EOF, the server enters the
192 shutdown phase. Interrupt is ignored. Anything else is interpreted
195 Text is minutes used, space, BTUs left. Both numbers are in
196 decimal. Clients shall ignore additional text separated by another
199 empire-client prints this prompt using format "[%d:%d] Command : ".
200 Clients with a tty-like user interface are advised to use a similar
201 format, to minimize differences to the examples in info.
203 * Argument prompt C_FLUSH
205 The server consumes a line of input and passes it to the currently
208 The server aborts the command on interrupt and EOF. Any argument
209 prompts it may send before the next command prompt do not consume
210 input. On EOF, the server then enters the shutdown phase (but see
211 C_EXECUTE for an exception).
213 If an update runs while the server waits for the line of input to
214 arrive, the current command is aborted. Whether the server consumes
215 a line of input for this argument prompt is unpredictable. Any
216 argument prompts it may send before the next command prompt do not
219 Text is a human-readable prompt supplied by the command.
221 empire-client prints the text verbatim.
225 Text is human-readable server output.
227 empire-client prints the text verbatim.
231 Request execution of a batch file. The text is whatever was on the
232 line of input after the execute command. Its syntax and semantics
233 are left to the client.
235 empire-client interprets the first word (sequence of non-space
236 characters) in the text as file name, and sends the contents of that
239 The security considerations on C_PIPE (below) apply to C_EXECUTE as
242 Note that servers before 4.3.11 sent a copy of the execute command's
243 first argument as text. This made it hard for clients to ensure
244 that the text is identical to what was sent, because the server
245 strips funny characters and interprets and strips '"' characters
246 when splitting input lines into command and arguments.
248 empire-client gets confused when old servers mangle the text that
251 The client shall mark the end of the batch file by signalling EOF as
252 described above. This does not terminate the session. It may
253 signal interrupt if it is unable or unwilling to send the complete
256 While executing the batch file, the server rejects redirections and
257 execute commands, and sends no C_PROMPT command prompts. It still
258 sends C_FLUSH argument prompts.
260 Protocol flaw: not sending C_PROMPT here screws up redirections:
261 they'd apply until the next C_PROMPT, i.e. from start of redirected
262 command until end of containing batch file. That's why the server
263 rejects redirections in batch files.
265 Certain bad failures make the server ignore the rest of the batch
266 file file. This feature is too hard to predict to be really useful.
268 Protocol flaw: strictly asynchronous clients cannot support
269 C_EXECUTE correctly. By the time C_EXECUTE arrives, the client may
270 have sent more input already. That input `overtakes' the contents
271 of the batch file in the input stream, and is interpreted as part of
272 the batch file. Because this is almost certain to happen when the
273 execute comes from a batch file, the server rejects execute commands
276 empire-client has this problem.
278 Clients are not required to support C_EXECUTE. Clients are
279 encouraged to offer alternative means for scripting.
283 Asynchronous message. The client should display the text
286 empire-client prints the text verbatim, prepended by a line feed.
287 This is clearly sub-optimal, because it can be inserted in the
288 middle of user input. Clients wishing to to display asynchronous
289 messages together with normal I/O should insert them before the
292 Although asynchronous messages can be switched off with the toggle
293 command, client support for C_FLASH is not really optional, because
294 a C_FLASH could arrive before the client manages to switch them off.
295 And if the client lets the user send arbitrary commands, the user
296 can switch it back on at any time. A session option controlling
297 C_FLASH would make more sense. Since all popular clients support
298 C_FLASH, it's not worth the trouble.
302 Notification that the number of unread telegrams changed. The text
303 is the notification in human-readable form.
305 empire-client prints the last received C_INFORM text right before
306 each prompt. It also repeats the last prompt when a C_INFORM
307 arrives. This is sub-optimal just like its treatment of C_FLASH.
309 The user can switch these off with the toggle command. Client
310 support is not really optional for the same reasons as for C_FLASH.
314 When a command is redirected to a pipeline, its output is preceded
315 by a C_PIPE line. The text is a copy of the redirection, starting
316 with '|'. Syntax and semantics of the text after the '|' are left
319 empire-client executes text after '|' as shell command, with
320 standard input connected to the Empire command's output.
322 The redirection applies to a single command, i.e. until the next
325 For obvious security reasons, clients supporting pipes shall ensure
326 that the text is identical to whatever was sent to the server. Note
327 that the server recognizes redirection only in command lines, not
328 argument lines. Asynchronous clients cannot distinguish the two.
330 empire-client prepares for redirections being recognized in any
331 line, and copes with only some of them being actually recognized.
335 When a command is redirected to a file, its output is preceded by a
336 C_REDIR line. The text is a copy of the redirection, starting with
337 '>', optionally followed by '>' or '!'. Syntax and semantics of the
338 remaining text are left to the client.
340 empire-client interprets the first word (sequence of non-space
341 characters) in the remaining text as file name, and redirects the
342 command's output to that file. The use of the first word is
343 unfortunate, as it arbitrarily limits the user's choice of file
344 names. If the text starts with '>!', it silently overwrites any
345 existing file, with '>>' it appends to the file, and with just '>'
346 it refuses to overwrite an existing file.
348 The redirection applies to a single command, i.e. until the next
351 The security considerations on C_PIPE apply to C_REDIR as well.
355 Other ids do not occur currently. Clients shall deal gracefully
356 with ids they don't know.
358 empire-client treats unknown ids like C_DATA. Versions before
359 4.3.11 prepend "Aborted\n" to C_ABORT lines, and "Error; " to
360 C_CMDERR and C_BADCMD lines for historical reasons.
365 In the shutdown phase, the server first sends a C_EXIT message. Its
366 text is a human-readable farewell.
368 empire-client prints this text prepended with "Exit: ".
370 The server then waits for the output queue to drain, then shuts down
371 the output direction of the connection. This makes the client detect
372 an end-of-file condition after it received all output. The client
373 should then close its end of the connection. The server continues to
374 read and ignore input until it detects an end-of-file condition. It
375 then closes its end of the connection, and the session terminates.
377 If the server closed its end of the connection without waiting for the
378 client to close the other end first, asynchronous clients could lose
379 output: an attempt to send input after the server closed its end would
380 fail with a connection reset error even when some output is still in
381 flight. Versions before 4.3.30 could misbehave like that in certain
384 If the shutdown phase doesn't complete within login_grace_time
385 (default 120s), the server closes the connection immediately. Output
391 Session options control client preferences. They are not persistent;
392 each session starts with the same default session options.
394 The only session option so far is utf-8. It controls whether to use
395 ASCII (disabled) or UTF-8 (enabled). Initial value is disabled.
396 Setting it to 0 disables, setting it to 1 enables, and the implied
399 Session options should not be confused with command toggle, which
400 controls player preferences. Clients should leave those accessible to
404 Commands Useful for Clients
405 ===========================
410 A number of commands are available for clients that wish to maintain
411 their own game state. These commands are called dumps.
413 dump - Dump sector information
414 ldump - Dump land unit information
415 lost - Report lost items
416 ndump - Dump nuclear stockpile information
417 pdump - Dump plane information
418 sdump - Dump ship information
420 See the various info pages on these for complete documentation on how
421 they work and how you can use them to help improve your clients.
423 Each of the above commands prints a timestamp, which is a decimal
424 number. This together with the timestamp selector enables you to dump
425 incrementally, i.e. retrieve only what changed since another dump.
426 For instance, if `dump *' printed timestamp 855544597, `dump *
427 ?timestamp>855544596' dumps everything changed since.
429 Note that the condition compares with the timestamp value minus one.
430 That's because timestamps have a noticeable granularity: things may
431 change between a dump and the next timestamp increase.
433 Timestamp values are currently seconds since the epoch, but this might
434 change, and clients are advised not to rely on it.
439 Traditional dumps have a number of shortcomings. They cover only the
440 most important part of the game state (sectors, ships, planes, land
441 units, nukes), but not game configuration, loans, news, and so forth.
442 They are not quite complete even for what they attempt to cover.
443 Finally, their output is harder to parse than necessary.
445 The new `xdump' command is designed to overcome these deficiencies.
446 See doc/xdump for the full story.
449 Advice on parsing human-readable command output
450 ===============================================