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 An Empire session consists of two phases: login and playing.
57 emp_client is synchronous during the former and asynchronous during
63 In the login phase, the server prompts for login commands.
65 The server starts with a C_INIT prompt. The login phase ends when the
66 server sends another C_INIT prompt, which starts the playing phase, or
67 when it closes the connection.
69 The server replies to a login command with another prompt. Except as
70 noted below, the server replies C_BADCMD for syntax errors, C_CMDERR
71 for other errors, and C_CMDOK on success. In any case, the prompt
72 text contains further information intended for humans.
78 Identify the client. This is optional. If given, version
79 information should be included.
83 Set country name to COUNTRY.
87 Country must be logged in.
89 If another connection is open for this country, forcibly close it,
90 else do nothing. Reply is C_EXIT in either case.
92 * options OPTION[=VALUE]...
94 Negotiate session options. Each argument requests setting OPTION to
95 VALUE. The string VALUE is interpreted in an option-specific way.
96 The form without the `=' sets it to an option-specific implied
99 The server accepts the request by sending C_CMDOK. If the server
100 encounters an unknown option, it rejects the request by sending
101 C_BADCMD. It rejects unsupported values by sending C_CMDERR. It
102 may or may not process valid parts of such a rejected request.
104 If there are no arguments, the server lists its options. For each
105 option, it sends a C_DATA line with OPTION=VALUE as text.
107 See below for supported session options.
111 Log in. Country name must be set already.
113 * play [USER [COUNTRY [PASSWORD]]]
115 Optional argument USER sets the user name.
117 Optional argument COUNTRY sets the country name.
119 Optional argument PASSWORD logs in. If it isn't present, the
120 country must be logged in already.
122 If another connection is open for this country, the server replies
125 On success, the server sends C_INIT. The text is the protocol
126 version number in decimal, currently 2. The client should terminate
127 on protocol versions it doesn't know how to handle.
129 The protocol version is not expected to change often. In fact, it
130 hasn't changed since the oldest known versions of Empire.
132 Unlike the first C_INIT, the second one is not a prompt, i.e the
133 server does not consume a line of input for it.
135 The session then proceeds to the playing phase.
139 Terminate the session. The server replies with C_EXIT and closes
144 List all countries that are still in sanctuary. The output consists
145 of a number of C_DATA lines with human-readable text.
147 This command is only recognized if option BLITZ is enabled.
151 Set the user name. This is optional and defaults to "".
156 In the playing phase, the server sends data, control and prompt lines.
158 Clients signal `EOF' by sending a line "ctld\n", and `interrupt' by
159 sending "aborted\n". The server treats these conditions specially, as
160 described below. Anything else is either a command or input for a
161 command, depending on how the server prompts for the line.
163 The following ids occur:
165 * Command prompt C_PROMPT
167 The server consumes a line of input. On EOF, the server terminates
168 the session. Interrupt is ignored. Anything else is interpreted as
171 Text is minutes used, space, BTUs left. Both numbers are in
172 decimal. Clients shall ignore additional text separated by another
175 emp_client prints this prompt using format "[%d:%d] Command : ".
176 Clients with a tty-like user interface are advised to use a similar
177 format, to minimize differences to the examples in info.
181 The server consumes a line of input and passes it to the currently
182 executing command. Commands usually fail on EOF or interrupt.
184 Text is a human-readable prompt supplied by the command.
186 emp_client prints the text verbatim.
190 Text is human-readable server output.
192 emp_client prints the text verbatim.
196 Request execution of a script. The text is a copy of the execute
197 command's first argument. Its syntax and semantics is left to the
200 emp_client interprets the text as file name, and sends the contents
203 The client shall mark the end of the script by signalling EOF as
204 described above. It may signal interrupt if it is unable or
205 unwilling to send the complete script.
207 While executing the script, the server sends no C_PROMPT command
208 prompts. It still sends C_FLUSH sub-prompts.
210 Certain bad failures make the server ignore the rest of the script
211 file. This feature is too hard to predict to be really useful.
213 Strictly asynchronous clients cannot support C_EXECUTE correctly.
214 By the time C_EXECUTE arrives, the client may have sent more input
215 already. That input `overtakes' the script in the input stream.
217 emp_client has this problem.
219 Clients are not required to support C_EXECUTE. Clients are
220 encouraged to offer alternative means for scripting.
224 End of session. The server will close the connection. Text is a
225 human-readable farewell.
227 emp_client prints this text prepended with "Exit: ".
231 Asynchronous message. The client should display the text
234 emp_client prints the text verbatim, prepended by a newline. This
235 is clearly sub-optimal, because it can be inserted in the middle of
236 user input. Clients wishing to to display asynchronous messages
237 together with normal I/O should insert them before the current
240 Although asynchronous messages can be switched off with the toggle
241 command, client support for C_FLASH is not really optional, because
242 a C_FLASH could arrive before the client manages to switch them off.
243 And if the client lets the user send arbitrary commands, the user
244 can switch it back on at any time. A session option controlling
245 C_FLASH would make more sense. Since all popular clients support
246 C_FLASH, it's not worth the trouble.
250 Notification that the number of unread telegrams changed. The text
251 is the notification in human-readable form.
253 emp_client prints the last received C_INFORM text right before each
254 prompt. It also repeats the last prompt when a C_INFORM arrives.
255 This is sub-optimal just like its treatment of C_FLASH.
257 The user can switch these off with the toggle command. Client
258 support is not really optional for the same reasons as for C_FLASH.
262 When a command is redirected to a pipeline, its output is prededed
263 by a C_PIPE line. The text is a copy of the redirection, starting
264 with '|'. Syntax and semantics of the text after the '|' are left
267 emp_client executes text after '|' as shell command, with standard
268 input connected to the Empire command's output.
270 For obvious security reasons, clients supporting pipes shall ensure
271 that the text is identical to whatever was sent to the server. Note
272 that the server recognizes redirection only in command lines, not
273 argument lines. Asynchronous clients cannot distinguish the two.
275 emp_client prepares for redirections being recognized in any line,
276 and copes with only some of them being actually recognized.
280 When a command is redirected to a file, its output is prededed by a
281 C_REDIR line. The text is a copy of the redirection, starting with
282 '>', optionally followed by '>' or '!'. Syntax and semantics of the
283 remaining text are left to the client.
285 emp_client interprets the first word (sequence of non-space
286 characters) in the remaining text as file name, and redirects the
287 command's output to that file. The use of the first word is
288 unfortunate, as it arbitrarily limits the user's choice of file
289 names. If the text starts with '>!', it silently overwrites any
290 existing file, with '>>' it appends to the file, and with just '>'
291 it refuses to overwrite an existing file.
293 The security considerations on C_PIPE apply to C_REDIR as well.
297 Other ids do not occur currently. Clients shall deal gracefully
298 with ids they don't know.
300 emp_client treats unknown ids like C_DATA. For historical reasons,
301 it prepends "Aborted\n" to C_ABORT lines, and "Error; " to C_CMDERR
308 Session options control client preferences. They are not persistent;
309 each session starts with the same default session options.
311 The only session option so far is utf-8. It controls whether to use
312 ASCII (disabled) or UTF-8 (enabled). Initial value is disabled.
313 Setting it to 0 disables, setting it to 1 enables, and the implied
316 Session options should not be confused with command toggle, which
317 controls player preferences. Clients should leave those accessible to
321 Commands Useful for Clients
322 ===========================
327 A number of commands are available for clients that wish to maintain
328 their own game state. These commands are called dumps.
330 dump - Dump sector information
331 ldump - Dump land unit information
332 lost - Report lost items
333 ndump - Dump nuclear stockpile information
334 pdump - Dump plane information
335 sdump - Dump ship information
337 See the various info pages on these for complete documentation on how
338 they work and how you can use them to help improve your clients.
340 Each of the above commands prints a timestamp, which is a decimal
341 number. This together with the timestamp selector enables you to dump
342 incrementally, i.e. retrieve only what changed since another dump.
343 For instance, if `dump *' printed timestamp 855544597, `dump *
344 ?timestamp>855544596' dumps everything changed since.
346 Note that the condition compares with the timestamp value minus one.
347 That's because timestamps have a noticeable granularity: things may
348 change between a dump and the next timestamp increase.
350 Timestamp values are currently seconds since the epoch, but this might
351 change, and clients are advised not to rely on it.
353 Experimental extended dump
354 --------------------------
356 Traditional dumps have a number of shortcomings. They cover only the
357 most important part of the game state: sectors, ships, planes, land
358 units, nukes, but not game configuration, loans, news, and so forth.
359 They are not quite complete even for what they attempt to cover.
360 Finally, their output is harder to parse than necessary.
362 The new `xdump' command is designed to overcome these deficiencies.
363 It still needs significant work, and is subject to change in
364 incompatible ways. To protect real games from known and unknown flaws
365 in xdump, it is only accessible when option GUINEA_PIGS is enabled.
367 Technical xdump documentation to be written.
370 Advice on parsing human-readable command output
371 ===============================================