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 a
16 character identifying the line, followed by a space, then arbitrary
17 text, then a line feed.
19 Identification characters encode small integers called output ids.
20 Ids less than 10 are encoded as decimal digits, and larger ids as
21 lower case letters, starting with 'a'. Symbolic names for ids are
24 Clients shall be able to safely handle output lines of arbitrary
25 length. Naturally, a client may not be able to handle a sufficiently
26 large line without loss of functionality, but safety must be ensured.
28 When using ASCII, the most significant bit in text characters
29 indicates highlighting.
31 The following control characters have a defined meaning:
33 ASCII name decimal meaning
34 ----------------------------------------------------
35 horizontal tab 9 move to next tab stop(1)
36 line feed 10 end of line
37 shift out 14 begin highlighting(2)
38 shift in 15 end highlighting(2)
40 (1) Tab stops are every eight columns.
41 (2) Only if session uses UTF-8
43 Other ASCII control characters should not occur and may be ignored by
44 clients. Likewise, overlong or malformed UTF-8 sequences should not
45 occur and may be ignored.
47 The server prompts for input. Each prompt `consumes' one line of
48 input. Input lines are arbitrary text, terminated by line feed, which
49 is optionally preceded by carriage return (decimal 13). Lines should
50 not contain ASCII control characters other than horizontal tab.
51 Clients should not send overlong or malformed UTF-8 sequences.
53 A client is called synchronous if it waits for a prompt before it
54 sends another line of input. Else it is called asynchronous.
56 Asynchronous clients must take care to avoid blocking on sending
57 input. If the client process blocks that way, it can't receive server
58 output until the server reads more input. That may never happen,
59 because the server may well block on output, which then deadlocks the
62 An Empire session consists of two phases: login and playing.
63 emp_client is synchronous during the former and asynchronous during
64 the latter. It can currently deadlock as described above.
69 In the login phase, the server prompts for login commands.
71 The server starts with a C_INIT prompt. The login phase ends when the
72 server sends another C_INIT prompt, which starts the playing phase, or
73 when it closes the connection.
75 The server replies to a login command with another prompt. Except as
76 noted below, the server replies C_BADCMD for syntax errors, C_CMDERR
77 for other errors, and C_CMDOK on success. In any case, the prompt
78 text contains further information intended for humans.
84 Identify the client. This is optional. If given, version
85 information should be included.
89 Set country name to COUNTRY.
93 If another connection is open for this country, forcibly close it,
94 else do nothing. Country must be authenticated.
96 Reply is C_EXIT regardless of success.
98 * options OPTION[=VALUE]...
100 Negotiate session options. Each argument requests setting OPTION to
101 VALUE. The string VALUE is interpreted in an option-specific way.
102 The form without the `=' sets it to an option-specific implied
105 The server accepts the request by sending C_CMDOK. If the server
106 encounters an unknown option, it rejects the request by sending
107 C_BADCMD. It rejects unsupported values by sending C_CMDERR. It
108 may or may not process valid parts of rejected requests.
110 If there are no arguments, the server lists its options. For each
111 option, it sends a C_DATA line with OPTION=VALUE as text.
113 See below for supported session options.
117 Authenticate. Country name must be set already.
119 * play [USER [COUNTRY [PASSWORD]]]
123 Optional argument USER sets the user name.
125 Optional argument COUNTRY sets the country name.
127 Optional argument PASSWORD authenticates. If it isn't present, the
128 country must be authenticated already.
130 Some error conditions result in a C_EXIT reply. Clients should
131 treat it just like C_CMDERR.
133 On success, the server sends C_INIT. The text is the protocol
134 version number in decimal, currently 2. The client should terminate
135 on protocol versions it doesn't know how to handle.
137 The protocol version is not expected to change often. In fact, it
138 hasn't changed since the oldest known versions of Empire.
140 Unlike the first C_INIT, the second one is not a prompt, i.e the
141 server does not consume a line of input for it.
143 The session then proceeds to the playing phase.
147 Terminate the session. The server replies with C_EXIT and closes
152 List all countries that are still in sanctuary. The output consists
153 of a number of C_DATA lines with human-readable text.
155 This command is only recognized if option BLITZ is enabled.
159 Set the user name. This is optional and defaults to "".
164 In the playing phase, the server sends data, control and prompt lines.
166 Clients signal `EOF' by sending a line "ctld\n", and `interrupt' by
167 sending "aborted\n". The server treats these conditions specially, as
168 described below. Anything else is either a command or input for a
169 command, depending on how the server prompts for the line.
171 The following ids occur:
173 * Command prompt C_PROMPT
175 The server consumes a line of input. On EOF, the server terminates
176 the session. Interrupt is ignored. Anything else is interpreted as
179 Text is minutes used, space, BTUs left. Both numbers are in
180 decimal. Clients shall ignore additional text separated by another
183 emp_client prints this prompt using format "[%d:%d] Command : ".
184 Clients with a tty-like user interface are advised to use a similar
185 format, to minimize differences to the examples in info.
189 The server consumes a line of input and passes it to the currently
190 executing command. Commands usually fail on EOF or interrupt.
192 Text is a human-readable prompt supplied by the command.
194 emp_client prints the text verbatim.
198 Text is human-readable server output.
200 emp_client prints the text verbatim.
204 Request execution of a script. The text is a copy of the execute
205 command's first argument. Its syntax and semantics is left to the
208 emp_client interprets the text as file name, and sends the contents
211 The security considerations on C_PIPE (below) apply to C_EXECUTE as
214 The client shall mark the end of the script by signalling EOF as
215 described above. It may signal interrupt if it is unable or
216 unwilling to send the complete script.
218 While executing the script, the server sends no C_PROMPT command
219 prompts. It still sends C_FLUSH sub-prompts.
221 Certain bad failures make the server ignore the rest of the script
222 file. This feature is too hard to predict to be really useful.
224 Strictly asynchronous clients cannot support C_EXECUTE correctly.
225 By the time C_EXECUTE arrives, the client may have sent more input
226 already. That input `overtakes' the script in the input stream.
228 emp_client has this problem.
230 Clients are not required to support C_EXECUTE. Clients are
231 encouraged to offer alternative means for scripting.
235 End of session. The server will close the connection. Text is a
236 human-readable farewell.
238 emp_client prints this text prepended with "Exit: ".
242 Asynchronous message. The client should display the text
245 emp_client prints the text verbatim, prepended by a newline. This
246 is clearly sub-optimal, because it can be inserted in the middle of
247 user input. Clients wishing to to display asynchronous messages
248 together with normal I/O should insert them before the current
251 Although asynchronous messages can be switched off with the toggle
252 command, client support for C_FLASH is not really optional, because
253 a C_FLASH could arrive before the client manages to switch them off.
254 And if the client lets the user send arbitrary commands, the user
255 can switch it back on at any time. A session option controlling
256 C_FLASH would make more sense. Since all popular clients support
257 C_FLASH, it's not worth the trouble.
261 Notification that the number of unread telegrams changed. The text
262 is the notification in human-readable form.
264 emp_client prints the last received C_INFORM text right before each
265 prompt. It also repeats the last prompt when a C_INFORM arrives.
266 This is sub-optimal just like its treatment of C_FLASH.
268 The user can switch these off with the toggle command. Client
269 support is not really optional for the same reasons as for C_FLASH.
273 When a command is redirected to a pipeline, its output is prededed
274 by a C_PIPE line. The text is a copy of the redirection, starting
275 with '|'. Syntax and semantics of the text after the '|' are left
278 emp_client executes text after '|' as shell command, with standard
279 input connected to the Empire command's output.
281 For obvious security reasons, clients supporting pipes shall ensure
282 that the text is identical to whatever was sent to the server. Note
283 that the server recognizes redirection only in command lines, not
284 argument lines. Asynchronous clients cannot distinguish the two.
286 emp_client prepares for redirections being recognized in any line,
287 and copes with only some of them being actually recognized.
291 When a command is redirected to a file, its output is prededed by a
292 C_REDIR line. The text is a copy of the redirection, starting with
293 '>', optionally followed by '>' or '!'. Syntax and semantics of the
294 remaining text are left to the client.
296 emp_client interprets the first word (sequence of non-space
297 characters) in the remaining text as file name, and redirects the
298 command's output to that file. The use of the first word is
299 unfortunate, as it arbitrarily limits the user's choice of file
300 names. If the text starts with '>!', it silently overwrites any
301 existing file, with '>>' it appends to the file, and with just '>'
302 it refuses to overwrite an existing file.
304 The security considerations on C_PIPE apply to C_REDIR as well.
308 Other ids do not occur currently. Clients shall deal gracefully
309 with ids they don't know.
311 emp_client treats unknown ids like C_DATA. For historical reasons,
312 it prepends "Aborted\n" to C_ABORT lines, and "Error; " to C_CMDERR
319 Session options control client preferences. They are not persistent;
320 each session starts with the same default session options.
322 The only session option so far is utf-8. It controls whether to use
323 ASCII (disabled) or UTF-8 (enabled). Initial value is disabled.
324 Setting it to 0 disables, setting it to 1 enables, and the implied
327 Session options should not be confused with command toggle, which
328 controls player preferences. Clients should leave those accessible to
332 Commands Useful for Clients
333 ===========================
338 A number of commands are available for clients that wish to maintain
339 their own game state. These commands are called dumps.
341 dump - Dump sector information
342 ldump - Dump land unit information
343 lost - Report lost items
344 ndump - Dump nuclear stockpile information
345 pdump - Dump plane information
346 sdump - Dump ship information
348 See the various info pages on these for complete documentation on how
349 they work and how you can use them to help improve your clients.
351 Each of the above commands prints a timestamp, which is a decimal
352 number. This together with the timestamp selector enables you to dump
353 incrementally, i.e. retrieve only what changed since another dump.
354 For instance, if `dump *' printed timestamp 855544597, `dump *
355 ?timestamp>855544596' dumps everything changed since.
357 Note that the condition compares with the timestamp value minus one.
358 That's because timestamps have a noticeable granularity: things may
359 change between a dump and the next timestamp increase.
361 Timestamp values are currently seconds since the epoch, but this might
362 change, and clients are advised not to rely on it.
367 Traditional dumps have a number of shortcomings. They cover only the
368 most important part of the game state (sectors, ships, planes, land
369 units, nukes), but not game configuration, loans, news, and so forth.
370 They are not quite complete even for what they attempt to cover.
371 Finally, their output is harder to parse than necessary.
373 The new `xdump' command is designed to overcome these deficiencies.
374 See doc/xdump for the full story.
377 Advice on parsing human-readable command output
378 ===============================================