1 This file contains material useful for client writers.
6 Empire's client server protocol is plain text. It is simple enough
7 that you could play using nothing more than telnet. That's a feature.
9 A session uses either ASCII or UTF-8, controlled by session option
10 utf-8. See below for session options. The session always starts in
13 Client-server communication is line-oriented.
15 The server sends lines of output. Each output line starts with an
16 identification string, followed by a space, then arbitrary text, then
19 Identification strings encode small integers called output ids as base
20 36 numbers. Characters '0' to '9' represent digits 0 to 9, and 'a' to
21 'z' represent 10..35, as do 'A' to 'Z'. Symbolic names for ids are
24 emp_client versions before version 4.3.11 parse large output ids
25 incorrectly. Such ids do not currently occur.
27 Clients shall be able to safely handle output lines of arbitrary
28 length. Naturally, a client may not be able to handle a sufficiently
29 large line without loss of functionality, but safety must be ensured.
31 When using ASCII, the most significant bit in text characters
32 indicates highlighting.
34 The following control characters have a defined meaning:
36 ASCII name decimal meaning
37 ----------------------------------------------------
38 horizontal tab 9 move to next tab stop(1)
39 line feed 10 end of line
40 shift out 14 begin highlighting(2)
41 shift in 15 end highlighting(2)
43 (1) Tab stops are every eight columns.
44 (2) Only if session uses UTF-8
46 Other ASCII control characters should not occur and may be ignored by
47 clients. Likewise, overlong or malformed UTF-8 sequences should not
48 occur and may be ignored.
50 The server prompts for input. Each prompt `consumes' one line of
51 input (except for C_EXECUTE, and when the update aborts a command, as
52 described below). Input lines are arbitrary text, terminated by line
53 feed, which is optionally preceded by carriage return (decimal 13).
54 Lines should not contain ASCII control characters other than
55 horizontal tab. Clients should not send overlong or malformed UTF-8
58 A client is called synchronous if it waits for a prompt before it
59 sends another line of input. Else it is called asynchronous.
61 Asynchronous clients must take care to avoid blocking on sending
62 input. If the client process blocks that way, it can't receive server
63 output until the server reads more input. That may never happen,
64 because the server may well block on output, which then deadlocks the
67 An Empire session consists of two phases: login and playing.
68 emp_client is synchronous during the former and asynchronous during
69 the latter. Versions before 4.3.11 could deadlock as described above.
74 In the login phase, the server prompts for login commands.
76 The server starts with a C_INIT prompt. The login phase ends when the
77 server sends another C_INIT prompt, which starts the playing phase, or
78 when it closes the connection.
80 The server replies to a login command with another prompt. Except as
81 noted below, the server replies C_BADCMD for syntax errors, C_CMDERR
82 for other errors, and C_CMDOK on success. In any case, the prompt
83 text contains further information intended for humans.
89 Identify the client. This is optional. If given, version
90 information should be included.
94 Set country name to COUNTRY.
98 If another connection is open for this country, forcibly close it,
99 else do nothing. Country must be authenticated.
101 Reply is C_EXIT regardless of success.
103 * options OPTION[=VALUE]...
105 Negotiate session options. Each argument requests setting OPTION to
106 VALUE. The string VALUE is interpreted in an option-specific way.
107 The form without the `=' sets it to an option-specific implied
110 The server accepts the request by sending C_CMDOK. If the server
111 encounters an unknown option, it rejects the request by sending
112 C_BADCMD. It rejects unsupported values by sending C_CMDERR. It
113 may or may not process valid parts of rejected requests.
115 If there are no arguments, the server lists its options. For each
116 option, it sends a C_DATA line with OPTION=VALUE as text, and
117 finally a C_CMDOK. If it supports no options at all, it may reply
118 with C_BADCMD instead.
120 See below for supported session options.
124 Authenticate. Country name must be set already.
126 * play [USER COUNTRY PASSWORD]
130 If no arguments are given, the country must be authenticated
133 Else, argument USER sets the user name, COUNTRY sets the country
134 name, and PASSWORD authenticates.
136 Some error conditions result in a C_EXIT reply. Clients should
137 treat it just like C_CMDERR.
139 On success, the server sends C_INIT. The text is the protocol
140 version number in decimal, currently 2. The client should terminate
141 on protocol versions it doesn't know how to handle.
143 The protocol version is not expected to change often. In fact, it
144 hasn't changed since the oldest known versions of Empire.
146 Unlike the first C_INIT, the second one is not a prompt, i.e the
147 server does not consume a line of input for it.
149 The session then proceeds to the playing phase.
153 Terminate the session. The server replies with C_EXIT and closes
158 List all countries that are still in sanctuary. The output consists
159 of a number of C_DATA lines with human-readable text.
161 This command is only recognized if option BLITZ is enabled.
165 Set the user name. This is optional and defaults to "".
170 In the playing phase, the server sends data, control and prompt lines.
172 Clients signal `EOF' by sending a line "ctld\n", and `interrupt' by
173 sending "aborted\n". The server treats these conditions specially, as
174 described below. Anything else is either a command or input for a
175 command, depending on how the server prompts for the line.
177 emp_client signals `EOF' when it encounters an end-of-file condition
178 while reading player input. It signals `interrupt' when it catches
179 SIGINT, which is normally triggered by Ctrl-C.
181 The following ids occur:
183 * Command prompt C_PROMPT
185 The server consumes a line of input. On EOF, the server terminates
186 the session. Interrupt is ignored. Anything else is interpreted as
189 Text is minutes used, space, BTUs left. Both numbers are in
190 decimal. Clients shall ignore additional text separated by another
193 emp_client prints this prompt using format "[%d:%d] Command : ".
194 Clients with a tty-like user interface are advised to use a similar
195 format, to minimize differences to the examples in info.
197 * Argument prompt C_FLUSH
199 The server consumes a line of input and passes it to the currently
200 executing command. Commands usually fail on interrupt. The server
201 terminates the session on EOF (but see C_EXECUTE for an exception).
203 If an update runs while the server waits for the line of input to
204 arrive, the current command is aborted. Whether the server consumes
205 a line of input for this argument prompt is unpredictable. Any
206 argument prompts it may send before the next command prompt do not
209 Text is a human-readable prompt supplied by the command.
211 emp_client prints the text verbatim.
215 Text is human-readable server output.
217 emp_client prints the text verbatim.
221 Request execution of a batch file. The text is whatever was on the
222 line of input after the execute command. Its syntax and semantics
223 are left to the client.
225 emp_client interprets the first word (sequence of non-space
226 characters) in the text as file name, and sends the contents of that
229 The security considerations on C_PIPE (below) apply to C_EXECUTE as
232 Note that servers before 4.3.11 sent a copy of the execute command's
233 first argument as text. This made it hard for clients to ensure
234 that the text is identical to what was sent, because the server
235 strips funny characters and interprets and strips '"' characters
236 when splitting input lines into command and arguments.
238 emp_client gets confused when old servers mangle the text that way.
240 The client shall mark the end of the batch file by signalling EOF as
241 described above. This does not terminate the session. It may
242 signal interrupt if it is unable or unwilling to send the complete
245 While executing the batch file, the server rejects redirections and
246 execute commands, and sends no C_PROMPT command prompts. It still
247 sends C_FLUSH argument prompts.
249 Protocol flaw: not sending C_PROMPT here screws up redirections:
250 they'd apply until the next C_PROMPT, i.e. from start of redirected
251 command until end of containing batch file. That's why the server
252 rejects redirections in batch files.
254 Certain bad failures make the server ignore the rest of the batch
255 file file. This feature is too hard to predict to be really useful.
257 Protocol flaw: strictly asynchronous clients cannot support
258 C_EXECUTE correctly. By the time C_EXECUTE arrives, the client may
259 have sent more input already. That input `overtakes' the contents
260 of the batch file in the input stream, and is interpreted as part of
261 the batch file. Because this is almost certain to happen when the
262 execute comes from a batch file, the server rejects execute commands
265 emp_client has this problem.
267 Clients are not required to support C_EXECUTE. Clients are
268 encouraged to offer alternative means for scripting.
272 End of session. The server is about to close the connection. Text
273 is a human-readable farewell.
275 emp_client prints this text prepended with "Exit: ".
279 Asynchronous message. The client should display the text
282 emp_client prints the text verbatim, prepended by a line feed. This
283 is clearly sub-optimal, because it can be inserted in the middle of
284 user input. Clients wishing to to display asynchronous messages
285 together with normal I/O should insert them before the current
288 Although asynchronous messages can be switched off with the toggle
289 command, client support for C_FLASH is not really optional, because
290 a C_FLASH could arrive before the client manages to switch them off.
291 And if the client lets the user send arbitrary commands, the user
292 can switch it back on at any time. A session option controlling
293 C_FLASH would make more sense. Since all popular clients support
294 C_FLASH, it's not worth the trouble.
298 Notification that the number of unread telegrams changed. The text
299 is the notification in human-readable form.
301 emp_client prints the last received C_INFORM text right before each
302 prompt. It also repeats the last prompt when a C_INFORM arrives.
303 This is sub-optimal just like its treatment of C_FLASH.
305 The user can switch these off with the toggle command. Client
306 support is not really optional for the same reasons as for C_FLASH.
310 When a command is redirected to a pipeline, its output is preceded
311 by a C_PIPE line. The text is a copy of the redirection, starting
312 with '|'. Syntax and semantics of the text after the '|' are left
315 emp_client executes text after '|' as shell command, with standard
316 input connected to the Empire command's output.
318 The redirection applies to a single command, i.e. until the next
321 For obvious security reasons, clients supporting pipes shall ensure
322 that the text is identical to whatever was sent to the server. Note
323 that the server recognizes redirection only in command lines, not
324 argument lines. Asynchronous clients cannot distinguish the two.
326 emp_client prepares for redirections being recognized in any line,
327 and copes with only some of them being actually recognized.
331 When a command is redirected to a file, its output is preceded by a
332 C_REDIR line. The text is a copy of the redirection, starting with
333 '>', optionally followed by '>' or '!'. Syntax and semantics of the
334 remaining text are left to the client.
336 emp_client interprets the first word (sequence of non-space
337 characters) in the remaining text as file name, and redirects the
338 command's output to that file. The use of the first word is
339 unfortunate, as it arbitrarily limits the user's choice of file
340 names. If the text starts with '>!', it silently overwrites any
341 existing file, with '>>' it appends to the file, and with just '>'
342 it refuses to overwrite an existing file.
344 The redirection applies to a single command, i.e. until the next
347 The security considerations on C_PIPE apply to C_REDIR as well.
351 Other ids do not occur currently. Clients shall deal gracefully
352 with ids they don't know.
354 emp_client treats unknown ids like C_DATA. Versions before 4.3.11
355 prepend "Aborted\n" to C_ABORT lines, and "Error; " to C_CMDERR and
356 C_BADCMD lines for historical reasons.
362 Session options control client preferences. They are not persistent;
363 each session starts with the same default session options.
365 The only session option so far is utf-8. It controls whether to use
366 ASCII (disabled) or UTF-8 (enabled). Initial value is disabled.
367 Setting it to 0 disables, setting it to 1 enables, and the implied
370 Session options should not be confused with command toggle, which
371 controls player preferences. Clients should leave those accessible to
375 Commands Useful for Clients
376 ===========================
381 A number of commands are available for clients that wish to maintain
382 their own game state. These commands are called dumps.
384 dump - Dump sector information
385 ldump - Dump land unit information
386 lost - Report lost items
387 ndump - Dump nuclear stockpile information
388 pdump - Dump plane information
389 sdump - Dump ship information
391 See the various info pages on these for complete documentation on how
392 they work and how you can use them to help improve your clients.
394 Each of the above commands prints a timestamp, which is a decimal
395 number. This together with the timestamp selector enables you to dump
396 incrementally, i.e. retrieve only what changed since another dump.
397 For instance, if `dump *' printed timestamp 855544597, `dump *
398 ?timestamp>855544596' dumps everything changed since.
400 Note that the condition compares with the timestamp value minus one.
401 That's because timestamps have a noticeable granularity: things may
402 change between a dump and the next timestamp increase.
404 Timestamp values are currently seconds since the epoch, but this might
405 change, and clients are advised not to rely on it.
410 Traditional dumps have a number of shortcomings. They cover only the
411 most important part of the game state (sectors, ships, planes, land
412 units, nukes), but not game configuration, loans, news, and so forth.
413 They are not quite complete even for what they attempt to cover.
414 Finally, their output is harder to parse than necessary.
416 The new `xdump' command is designed to overcome these deficiencies.
417 See doc/xdump for the full story.
420 Advice on parsing human-readable command output
421 ===============================================