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 Country must be logged in.
95 If another connection is open for this country, forcibly close it,
96 else do nothing. Reply is C_EXIT in either case.
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 such a rejected request.
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 Log in. Country name must be set already.
119 * play [USER [COUNTRY [PASSWORD]]]
121 Optional argument USER sets the user name.
123 Optional argument COUNTRY sets the country name.
125 Optional argument PASSWORD logs in. If it isn't present, the
126 country must be logged in already.
128 If another connection is open for this country, the server replies
131 On success, the server sends C_INIT. The text is the protocol
132 version number in decimal, currently 2. The client should terminate
133 on protocol versions it doesn't know how to handle.
135 The protocol version is not expected to change often. In fact, it
136 hasn't changed since the oldest known versions of Empire.
138 Unlike the first C_INIT, the second one is not a prompt, i.e the
139 server does not consume a line of input for it.
141 The session then proceeds to the playing phase.
145 Terminate the session. The server replies with C_EXIT and closes
150 List all countries that are still in sanctuary. The output consists
151 of a number of C_DATA lines with human-readable text.
153 This command is only recognized if option BLITZ is enabled.
157 Set the user name. This is optional and defaults to "".
162 In the playing phase, the server sends data, control and prompt lines.
164 Clients signal `EOF' by sending a line "ctld\n", and `interrupt' by
165 sending "aborted\n". The server treats these conditions specially, as
166 described below. Anything else is either a command or input for a
167 command, depending on how the server prompts for the line.
169 The following ids occur:
171 * Command prompt C_PROMPT
173 The server consumes a line of input. On EOF, the server terminates
174 the session. Interrupt is ignored. Anything else is interpreted as
177 Text is minutes used, space, BTUs left. Both numbers are in
178 decimal. Clients shall ignore additional text separated by another
181 emp_client prints this prompt using format "[%d:%d] Command : ".
182 Clients with a tty-like user interface are advised to use a similar
183 format, to minimize differences to the examples in info.
187 The server consumes a line of input and passes it to the currently
188 executing command. Commands usually fail on EOF or interrupt.
190 Text is a human-readable prompt supplied by the command.
192 emp_client prints the text verbatim.
196 Text is human-readable server output.
198 emp_client prints the text verbatim.
202 Request execution of a script. The text is a copy of the execute
203 command's first argument. Its syntax and semantics is left to the
206 emp_client interprets the text as file name, and sends the contents
209 The client shall mark the end of the script by signalling EOF as
210 described above. It may signal interrupt if it is unable or
211 unwilling to send the complete script.
213 While executing the script, the server sends no C_PROMPT command
214 prompts. It still sends C_FLUSH sub-prompts.
216 Certain bad failures make the server ignore the rest of the script
217 file. This feature is too hard to predict to be really useful.
219 Strictly asynchronous clients cannot support C_EXECUTE correctly.
220 By the time C_EXECUTE arrives, the client may have sent more input
221 already. That input `overtakes' the script in the input stream.
223 emp_client has this problem.
225 Clients are not required to support C_EXECUTE. Clients are
226 encouraged to offer alternative means for scripting.
230 End of session. The server will close the connection. Text is a
231 human-readable farewell.
233 emp_client prints this text prepended with "Exit: ".
237 Asynchronous message. The client should display the text
240 emp_client prints the text verbatim, prepended by a newline. This
241 is clearly sub-optimal, because it can be inserted in the middle of
242 user input. Clients wishing to to display asynchronous messages
243 together with normal I/O should insert them before the current
246 Although asynchronous messages can be switched off with the toggle
247 command, client support for C_FLASH is not really optional, because
248 a C_FLASH could arrive before the client manages to switch them off.
249 And if the client lets the user send arbitrary commands, the user
250 can switch it back on at any time. A session option controlling
251 C_FLASH would make more sense. Since all popular clients support
252 C_FLASH, it's not worth the trouble.
256 Notification that the number of unread telegrams changed. The text
257 is the notification in human-readable form.
259 emp_client prints the last received C_INFORM text right before each
260 prompt. It also repeats the last prompt when a C_INFORM arrives.
261 This is sub-optimal just like its treatment of C_FLASH.
263 The user can switch these off with the toggle command. Client
264 support is not really optional for the same reasons as for C_FLASH.
268 When a command is redirected to a pipeline, its output is prededed
269 by a C_PIPE line. The text is a copy of the redirection, starting
270 with '|'. Syntax and semantics of the text after the '|' are left
273 emp_client executes text after '|' as shell command, with standard
274 input connected to the Empire command's output.
276 For obvious security reasons, clients supporting pipes shall ensure
277 that the text is identical to whatever was sent to the server. Note
278 that the server recognizes redirection only in command lines, not
279 argument lines. Asynchronous clients cannot distinguish the two.
281 emp_client prepares for redirections being recognized in any line,
282 and copes with only some of them being actually recognized.
286 When a command is redirected to a file, its output is prededed by a
287 C_REDIR line. The text is a copy of the redirection, starting with
288 '>', optionally followed by '>' or '!'. Syntax and semantics of the
289 remaining text are left to the client.
291 emp_client interprets the first word (sequence of non-space
292 characters) in the remaining text as file name, and redirects the
293 command's output to that file. The use of the first word is
294 unfortunate, as it arbitrarily limits the user's choice of file
295 names. If the text starts with '>!', it silently overwrites any
296 existing file, with '>>' it appends to the file, and with just '>'
297 it refuses to overwrite an existing file.
299 The security considerations on C_PIPE apply to C_REDIR as well.
303 Other ids do not occur currently. Clients shall deal gracefully
304 with ids they don't know.
306 emp_client treats unknown ids like C_DATA. For historical reasons,
307 it prepends "Aborted\n" to C_ABORT lines, and "Error; " to C_CMDERR
314 Session options control client preferences. They are not persistent;
315 each session starts with the same default session options.
317 The only session option so far is utf-8. It controls whether to use
318 ASCII (disabled) or UTF-8 (enabled). Initial value is disabled.
319 Setting it to 0 disables, setting it to 1 enables, and the implied
322 Session options should not be confused with command toggle, which
323 controls player preferences. Clients should leave those accessible to
327 Commands Useful for Clients
328 ===========================
333 A number of commands are available for clients that wish to maintain
334 their own game state. These commands are called dumps.
336 dump - Dump sector information
337 ldump - Dump land unit information
338 lost - Report lost items
339 ndump - Dump nuclear stockpile information
340 pdump - Dump plane information
341 sdump - Dump ship information
343 See the various info pages on these for complete documentation on how
344 they work and how you can use them to help improve your clients.
346 Each of the above commands prints a timestamp, which is a decimal
347 number. This together with the timestamp selector enables you to dump
348 incrementally, i.e. retrieve only what changed since another dump.
349 For instance, if `dump *' printed timestamp 855544597, `dump *
350 ?timestamp>855544596' dumps everything changed since.
352 Note that the condition compares with the timestamp value minus one.
353 That's because timestamps have a noticeable granularity: things may
354 change between a dump and the next timestamp increase.
356 Timestamp values are currently seconds since the epoch, but this might
357 change, and clients are advised not to rely on it.
359 Experimental extended dump
360 --------------------------
362 Traditional dumps have a number of shortcomings. They cover only the
363 most important part of the game state: sectors, ships, planes, land
364 units, nukes, but not game configuration, loans, news, and so forth.
365 They are not quite complete even for what they attempt to cover.
366 Finally, their output is harder to parse than necessary.
368 The new `xdump' command is designed to overcome these deficiencies.
369 It still needs significant work, and is subject to change in
370 incompatible ways. To protect real games from known and unknown flaws
371 in xdump, it is only accessible when option GUINEA_PIGS is enabled.
373 Technical xdump documentation to be written.
376 Advice on parsing human-readable command output
377 ===============================================