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 security considerations on C_PIPE (below) apply to C_EXECUTE as
212 The client shall mark the end of the script by signalling EOF as
213 described above. It may signal interrupt if it is unable or
214 unwilling to send the complete script.
216 While executing the script, the server sends no C_PROMPT command
217 prompts. It still sends C_FLUSH sub-prompts.
219 Certain bad failures make the server ignore the rest of the script
220 file. This feature is too hard to predict to be really useful.
222 Strictly asynchronous clients cannot support C_EXECUTE correctly.
223 By the time C_EXECUTE arrives, the client may have sent more input
224 already. That input `overtakes' the script in the input stream.
226 emp_client has this problem.
228 Clients are not required to support C_EXECUTE. Clients are
229 encouraged to offer alternative means for scripting.
233 End of session. The server will close the connection. Text is a
234 human-readable farewell.
236 emp_client prints this text prepended with "Exit: ".
240 Asynchronous message. The client should display the text
243 emp_client prints the text verbatim, prepended by a newline. This
244 is clearly sub-optimal, because it can be inserted in the middle of
245 user input. Clients wishing to to display asynchronous messages
246 together with normal I/O should insert them before the current
249 Although asynchronous messages can be switched off with the toggle
250 command, client support for C_FLASH is not really optional, because
251 a C_FLASH could arrive before the client manages to switch them off.
252 And if the client lets the user send arbitrary commands, the user
253 can switch it back on at any time. A session option controlling
254 C_FLASH would make more sense. Since all popular clients support
255 C_FLASH, it's not worth the trouble.
259 Notification that the number of unread telegrams changed. The text
260 is the notification in human-readable form.
262 emp_client prints the last received C_INFORM text right before each
263 prompt. It also repeats the last prompt when a C_INFORM arrives.
264 This is sub-optimal just like its treatment of C_FLASH.
266 The user can switch these off with the toggle command. Client
267 support is not really optional for the same reasons as for C_FLASH.
271 When a command is redirected to a pipeline, its output is prededed
272 by a C_PIPE line. The text is a copy of the redirection, starting
273 with '|'. Syntax and semantics of the text after the '|' are left
276 emp_client executes text after '|' as shell command, with standard
277 input connected to the Empire command's output.
279 For obvious security reasons, clients supporting pipes shall ensure
280 that the text is identical to whatever was sent to the server. Note
281 that the server recognizes redirection only in command lines, not
282 argument lines. Asynchronous clients cannot distinguish the two.
284 emp_client prepares for redirections being recognized in any line,
285 and copes with only some of them being actually recognized.
289 When a command is redirected to a file, its output is prededed by a
290 C_REDIR line. The text is a copy of the redirection, starting with
291 '>', optionally followed by '>' or '!'. Syntax and semantics of the
292 remaining text are left to the client.
294 emp_client interprets the first word (sequence of non-space
295 characters) in the remaining text as file name, and redirects the
296 command's output to that file. The use of the first word is
297 unfortunate, as it arbitrarily limits the user's choice of file
298 names. If the text starts with '>!', it silently overwrites any
299 existing file, with '>>' it appends to the file, and with just '>'
300 it refuses to overwrite an existing file.
302 The security considerations on C_PIPE apply to C_REDIR as well.
306 Other ids do not occur currently. Clients shall deal gracefully
307 with ids they don't know.
309 emp_client treats unknown ids like C_DATA. For historical reasons,
310 it prepends "Aborted\n" to C_ABORT lines, and "Error; " to C_CMDERR
317 Session options control client preferences. They are not persistent;
318 each session starts with the same default session options.
320 The only session option so far is utf-8. It controls whether to use
321 ASCII (disabled) or UTF-8 (enabled). Initial value is disabled.
322 Setting it to 0 disables, setting it to 1 enables, and the implied
325 Session options should not be confused with command toggle, which
326 controls player preferences. Clients should leave those accessible to
330 Commands Useful for Clients
331 ===========================
336 A number of commands are available for clients that wish to maintain
337 their own game state. These commands are called dumps.
339 dump - Dump sector information
340 ldump - Dump land unit information
341 lost - Report lost items
342 ndump - Dump nuclear stockpile information
343 pdump - Dump plane information
344 sdump - Dump ship information
346 See the various info pages on these for complete documentation on how
347 they work and how you can use them to help improve your clients.
349 Each of the above commands prints a timestamp, which is a decimal
350 number. This together with the timestamp selector enables you to dump
351 incrementally, i.e. retrieve only what changed since another dump.
352 For instance, if `dump *' printed timestamp 855544597, `dump *
353 ?timestamp>855544596' dumps everything changed since.
355 Note that the condition compares with the timestamp value minus one.
356 That's because timestamps have a noticeable granularity: things may
357 change between a dump and the next timestamp increase.
359 Timestamp values are currently seconds since the epoch, but this might
360 change, and clients are advised not to rely on it.
362 Experimental extended dump
363 --------------------------
365 Traditional dumps have a number of shortcomings. They cover only the
366 most important part of the game state: sectors, ships, planes, land
367 units, nukes, but not game configuration, loans, news, and so forth.
368 They are not quite complete even for what they attempt to cover.
369 Finally, their output is harder to parse than necessary.
371 The new `xdump' command is designed to overcome these deficiencies.
372 It still needs significant work, and is subject to change in
373 incompatible ways. To protect real games from known and unknown flaws
374 in xdump, it is only accessible when option GUINEA_PIGS is enabled.
376 Technical xdump documentation to be written.
379 Advice on parsing human-readable command output
380 ===============================================