client: Unbreak standalone build
[empserver] / doc / xdump
1 Introduction
2
3 Empire is designed as a smart server with dumb clients.  An Empire
4 client need to know nothing about the game.  Even telnet would do.  In
5 fact, empire-client is little more than a slightly specialized telnet.
6
7 In such a design, presentation is in the server, and it is designed
8 for human consumption.  Ideally, presentation and logic are cleanly
9 separated, for easy selection between different presentations.
10 There's no such separation in the Empire server, and separating them
11 now would be a herculean effort.
12
13 Thus, smart clients have to work with output designed for humans.
14 That's not especially hard, just an awful lot of tedious work, and the
15 result gets easily broken by minor changes in output format, which
16 humans hardly notice.
17
18 Instead of making smart clients parse output of commands designed for
19 humans, one can add commands designed for machines.  Such commands can
20 share the code implementing game rules with their counterparts for
21 humans.  To do that cleanly means separating logic and presentation.
22 Implementing them with their own copy of the code is no good --- how
23 would you ensure that the two copies implement precisely the same game
24 rules?
25
26 Except for commands that actually don't do anything.  There's a useful
27 class of such commands: commands to show game configuration and state
28 without altering it.  The only game rules involved are those that
29 govern who gets to see what.  Ensuring that those are obeyed is
30 tractable.
31
32 Empire has had one such command since the beginning: dump.  Empire
33 4.0.6 added more: sdump, ldump, pdump and ndump.  4.0.7 added lost and
34 support for incremental dumps.  These commands have served smart
35 clients well.  However, they cover just the most important part of the
36 game state (sectors, ships, planes, land units, nukes), and no game
37 configuration.  They are not quite complete even for what they attempt
38 to cover.  Finally, their output is harder to parse than necessary.
39
40 The xdump command is designed to be the dump to end all dumps.
41
42 Like many good ideas, xdump has secondary uses.  Dumping game state as
43 text can be one half of a game export/import facility.  Useful to
44 migrate games to different machines or even, with some text mangling
45 perhaps, different server versions.  We will see below that xdump
46 isn't quite sufficient for that, but it's a start.
47
48 Means to import game configuration let you customize your game without
49 recompiling the server.  As we will see, configuration files have
50 different requirements, which xdump doesn't satisfy without some
51 extensions.
52
53 If game import code can edit everything, then a deity command capable
54 of editing everything is possible.  Proof-of-concept code exists (not
55 in the tree yet).
56
57
58 Analysis of the data to dump
59
60 Game state consists of a fixed set of table files (sector, ship, ...),
61 telegram files, and a few miscellaneous files.  Game configuration
62 consists of a fixed set of configuration tables and scalar parameters.
63
64 A table is an ordered set of records (table rows).  All records have
65 the same fields (table columns), which are statically typed.
66
67 Fields may be integers, floating-point numbers, x- or y-coordinates,
68 symbols and symbol sets encoded as integers in a way specific to the
69 server version, and character arrays.  Configuration table fields may
70 be pointers to zero-terminated strings, null pointers allowed.  No
71 other pointers occur.  Unions do not occur.
72
73
74 Requirements analysis
75
76 Requirements:
77
78 * Capable to dump all tables.
79
80 * Can do incremental dumps.
81
82 * Output is text.
83
84 * Output is reasonably compact.
85
86 * Output is trivial to parse.  Triviality test: if it's easy in AWK, C
87   (no lex & yacc, just stdio), Lisp (just reader) and Perl (base
88   language, no modules), then it's trivial enough.
89
90 * Output identifies itself.
91
92 * Output is self-contained; symbol encoding is explicit.
93
94 * KISS: Keep it simple, stupid.
95
96 Non-requirements:
97
98 * Generality.  We're not trying to design a general mechanism for
99   dumping C data.
100
101 * Completeness.  We're not trying to dump stuff other than tables.
102
103 * Abstraction.  We're not trying to hide how things are stored in the
104   server.  When storage changes, xdump output will change as well, and
105   consumers need to be updated.  This is not because abstraction
106   wouldn't be nice to have, just because we don't feel up to the task
107   of designing one.
108
109
110 Principles of Design
111
112 Traditional dumps have a dump function for every table.  These
113 functions are simple, but exceedingly dull and repetitive.
114
115 The selector code works differently.  Each table has a descriptor,
116 which among other things defines a dictionary of selector descriptors.
117 A selector descriptor describes a field (table column) visible to
118 players.  This is what we call meta-data (data about data).  The
119 selector code knows nothing about the individual tables, it just
120 interprets meta-data.  That's smart, as it keeps the dull, repetitive
121 parts in more easily maintainable meta-data rather than code.
122
123 xdump follows the selector design, and uses the existing selector
124 meta-data.  This requires extending the meta-data to configuration
125 tables, which weren't previously covered.  It also requires some
126 generalization of selector descriptors, so that all fields can be
127 covered.
128
129 To sum up, meta-data consists of a table of tables, and for each table
130 a table of selectors (table of columns, so to speak).  It is specific
131 to the server version and how it is compiled on the host.
132
133 To interpret a table xdump, you need its meta-data, because without it
134 you have no idea what the columns mean.  As meta-data is just a bunch
135 of tables, xdump can dump it.  But now you need meta-meta-data to make
136 sense of the meta-data.  Fortunately, meta-meta-data is the same for
137 all xdumps, and therefore the recursion terminates with a single
138 meta-meta-table.
139
140 xdump dumps symbols and symbol sets as integers.  To decode them, you
141 need to know what the symbol numbers and symbol set bits mean.  For
142 this purpose, field meta-data includes the table ID of a symbol table.
143 A symbol table is a table of value-name pairs, with the value in the
144 leftmost column.  You decode a symbol value by looking it up in the
145 symbol table.  You decode a symbol set value by looking up its bits
146 (powers of two) in the symbol table.
147
148 Some integer fields are actually keys in other tables.  For instance,
149 ship field type is a key in the table of ship types ship-chr, and
150 plane field ship is a key in the ship table.  Key -1 is special: it's
151 a null key.  Meta-data encodes these table reference just like for
152 symbols: the meta-data has the ID of the referenced table, and that
153 table has the key in the leftmost column.  Obviously, that leftmost
154 column is a table key as well, referencing the table itself.
155
156 A table with its key in the leftmost column can be dumped partially.
157 Without such a key, you need to count records to find the record
158 index, and that works only if you can see a prefix of the complete
159 table.
160
161
162 Syntax of xdump command
163
164 See info xdump.
165
166
167 The xdump output Language
168
169 Because the output is to be parsed by machines, it needs to be
170 precisely specified.  We use EBNF (ISO 14977) for syntax, except we
171 use '-' in meta-identifiers and omit the concatenation symbol ','.
172
173     table = header { record } footer ;
174     header = "XDUMP" space [ "meta" space ]
175              identifier space timestamp newline ;
176     identifier = id-char1 { id-char } ;
177     id-char1 = ? ASCII letter ? ;
178     id-char = ? ASCII characters 33..126 except '"#()<>=' ? ;
179     timestamp = intnum ;
180     footer = "/" number newline ;
181     record = [ fields ] newline ;
182     fields = field { space field } ;
183     field = intnum | flonum | string ;
184     intnum = ? integer in printf %d format ? ;
185     flonum = ? floating-point in printf %g format ? ;
186     string = "nil"
187            | '"' { str-char } '"' ;
188     str-char = "\\" octal-digit octal-digit octal-digit
189              | ? ASCII characters 33..126 except '"' and '\\' ? ;
190     octal-digit = ? '0'..'7' ? ;
191     space = ' ' ;
192     newline = ? ASCII character 10 ? ;
193
194 Notes:
195
196 * The syntax for flonum is debatable.  Precise conversion between
197   floating-point and decimal is hard, and C libraries are not required
198   to be precise.  Using C99's %a format for flonum would avoid the
199   issue, but some programming environments may have trouble converting
200   that back to floating-point.  We may change to %a anyway in the
201   future.  Clients are advised to accept both.
202
203 * Strings syntax could perhaps profit from the remaining C escape
204   sequences.  Except for '\"': adding that would complicate regular
205   expressions matching the string, and thus violate the `trivial to
206   parse' requirement
207
208 * Space is to be taken literally: a single space character.  Not a
209   non-empty sequence of white-space.
210
211 Semantics:
212
213 * The table identifier in the header is one of the names in xdump table.
214
215 * The timestamp increases monotonically.  It has a noticeable
216   granularity: game state may change between an xdump and the next
217   timestamp increase.  If the table has a timestamp field, clients can
218   xdump incrementally by using a conditional ?timestamp>T, where T is
219   one less than the timestamp received with the last xdump of that
220   table.
221
222   Timestamp values are currently seconds since the epoch, but this
223   might change, and clients are advised not to rely on it.
224
225 * The number in the footer matches the number of records.
226
227 * Fields match their meta-data (see Meta-Data below).
228
229 * "nil" represents a null string (which is not the same as an empty
230   string).  Otherwise, fields are to be interpreted just like C
231   literals.
232
233
234 Meta-Data
235
236 Table meta-data is in xdump table.  Fields:
237
238 * uid: The table ID, key for xdump table.  IDs depend on the server
239   version; clients should not hard-code them.  This is the leftmost
240   field.
241
242 * name: The table name.  Clients may identify tables by name.
243
244 Field meta-data for table T is in xdump meta T.  The order of fields
245 in the xdump T matches the order of records in xdump meta T.  Fields
246 of xdump meta T are:
247
248 * name: The field name.  Matches the selector name.  Clients may
249   identify fields by name.  This is the leftmost field.
250
251 * type: The field's data type, a symbol.  Clients should use this only
252   as key for the symbol table.  Symbols are:
253   - "d", field uses intnum syntax
254   - "g", field uses flonum syntax
255   - "s", field uses string syntax
256   - "c", field uses string syntax (only until version 4.3.33)
257
258 * flags: The field's flags, a symbol set.  Flags are:
259   - "deity", field visible only to deities
260   - "bits", field is a symbol set, field type must encode symbol "d",
261     field table must not be -1.
262   - "hidden", field value is masked for contact when option HIDDEN is
263     enabled.  Masked values are replaced by -1.
264
265 * len: If non-zero, then the record encodes an array with that many
266   elements.  The array is dumped as len fields.
267
268   Only until version 4.3.33: if field type encodes symbol "c", it is a
269   character array, and is dumped as a single string field.
270
271 * table: Key for xdump table.  Unless -1, it defines the table
272   referenced by the field value.  Field type must encode symbol "d"
273   then.
274
275 Symbol table fields:
276
277 * value: The symbol's encoding as integer.  If the symbol can be
278   element of a symbol set, this is a power of two.
279
280 * name: The symbol's name.
281
282
283 Notes on xdump Implementation
284
285 Overall impact on the server code is low.
286
287 To keeps xdump simple, storage of game state and game configuration
288 tables has been unified under the common empfile abstraction, making
289 nxtitem-iterators and selectors equally applicable to all tables.
290
291 xdump required a few extensions to meta-data, which may become useful
292 in other places as well:
293
294 * Selectors can now deal with arrays (revived struct castr member
295   ca_len).  Not yet available on the Empire command line.
296
297 * Selector meta-data can now express that a selector value is a key
298   for another table (new struct castr member ca_table).  The selector
299   code doesn't use that, yet.
300
301 * Redundant selectors can be marked so that xdump ignores them (new
302   struct castr member ca_dump).
303
304 Meta-data is in empfile[] (table meta-data), src/lib/global/nsc.c
305 (selector meta-data), src/lib/global/symbol.c (symbol tables).  The
306 command is in src/lib/commands/xdump.c, unsurprisingly.
307
308
309 Hints on Using xdump in Clients
310
311 Let's explore how to dump a game.  To make sense of a table, we need
312 its meta-data, and to make sense of that table, we need meta-meta
313 data.  So we start with that:
314
315     [3:640] Command : xdump meta meta
316     XDUMP meta meta 1466920477
317     "name" 3 0 0 -1
318     "type" 1 0 0 33
319     "flags" 1 8 0 32
320     "len" 1 0 0 -1
321     "table" 1 0 0 26
322     /5
323
324 To interpret this table, we have to know the field names and their
325 meanings.  Clients hard-code them.  They should be prepared to accept
326 and ignore additional fields, and to cope with changes in field order,
327 except they may rely on "name" coming first.
328
329 A word on hard-coding.  Clients hard-code *names*.  The numbers used
330 for table IDs and to encode symbols are none of the client's business.
331
332 The encoding doesn't normally change within a game.  Except when the
333 game is migrated to a sufficiently different server.  That's a rare
334 event.  Clients may wish to provide for such changes anyway, by
335 decoupling the client's encoding from the server's, and dumping fresh
336 meta-data on login.  Incremental meta-data dump would be nice to have.
337
338 So we don't know how symbol type and symbol set flags are encoded.  To
339 decode them, we need their symbol tables.  However, we need flags and
340 type only for tables we don't know, and there's one more table we do
341 know, namely the table of tables.  Let's dump that next, starting with
342 its meta-data:
343
344     [3:640] Command : xdump meta table
345     XDUMP meta table 1466920477
346     "uid" 1 0 0 26
347     "name" 3 0 0 -1
348     /2
349
350 Because xdump table is referenced from elsewhere (xdump meta meta
351 field table), the leftmost field must contain the key.  Thus, the
352 leftmost field's meta-data field table must be the table ID of xdump
353 table itself.  Indeed, its value matches the one we got in xdump meta
354 meta.  Let's try to dump the table:
355
356     [5:640] Command : xdump 26 *
357     XDUMP table 1466920477
358     0 "sect"
359     1 "ship"
360 [...]
361     8 "nat"
362 [...]
363     18 "sect-chr"
364     19 "ship-chr"
365 [...]
366     26 "table"
367 [...]
368     /48
369
370 It worked!
371
372 Now dump the two symbol tables we postponed.  Because xdump accepts
373 table IDs as well as names, we don't have to know their names:
374
375     [5:640] Command : xdump meta 33
376     XDUMP meta meta-type 1466920477
377     "value" 1 0 0 -1
378     "name" 3 0 0 -1
379     /2
380
381     [6:640] Command : xdump 33 *
382     XDUMP meta-type 1466920477
383     1 "d"
384     2 "g"
385     3 "s"
386     /3
387
388     [7:640] Command : xdump meta 32
389     XDUMP meta meta-flags 1466920477
390     "value" 1 0 0 -1
391     "name" 3 0 0 -1
392     /2
393
394     [7:640] Command : xdump 32 *
395     XDUMP meta-flags 1466920477
396     1 "deity"
397     8 "bits"
398     16 "hidden"
399     /3
400
401 We now have complete meta-meta information:
402
403     name  type         flags  len  table
404     -----------------------------------------
405     name     s       (const)    0
406     type     d       (const)    0  meta-type
407     flags    d  (bits const)    0  meta-flags
408     len      d       (const)    0
409     table    d       (const)    0  table
410
411 Dumping the remaining tables is easy: just walk the table of tables.
412 Here's the first one:
413
414     [7:640] Command : xdump meta 0
415     XDUMP meta sect 1466920477
416     "owner" 1 0 0 8
417     "xloc" 1 0 0 -1
418     "yloc" 1 0 0 -1
419     "des" 1 0 0 18
420 [...]
421     /78
422
423 A whole load of tables referenced!  Only one of them (not shown above)
424 is a symbol table.
425
426 owner references table nat.  No surprise.
427
428 xloc and yloc together reference the sector table, but that's not
429 expressed in meta-data (yet).
430
431 Let's stop here before this gets too long and boring.  Experiment
432 yourself!  Check out example Perl code scripts/xdump.pl.
433
434
435 Analysis of xdump as Configuration File Format
436
437 xdump makes a lousy configuration format because it is unwieldy to
438 edit for humans.  That's because configuration files have different
439 requirements than dumps:
440
441 * Can be edited by humans with common tools, including text editors
442   and spreadsheets.
443
444   Using text editors requires a nice fixed-width table layout.
445   Spreadsheet import requires trivial field separation.  Tab character
446   field separator or fixed width columns should do.  The syntax should
447   allow all that, but not require it.
448
449   Trouble spots:
450
451   - xdump's rigid horizontal and vertical spacing makes it impossible
452     to align things visually.
453
454   - xdump uses one line per record, which can lead to excessively long
455     lines.
456
457   - xdump's string syntax requires octal escape for space.
458
459   - No comment syntax.
460
461 * Each table is self-contained.  You don't have to look into other
462   tables to make sense of it.
463
464   This conflicts with xdump's separation of data and meta-data.  You
465   need the table's meta-data to identify fields, and the referenced
466   symbol tables to decode symbols.
467
468 * Easy to parse.  Don't compromise legibility just to please some dumb
469   tool, though.
470
471 Since we're trying to apply xdump to the configuration file problem,
472 we get an additional requirement:
473
474 * Reasonably close to xdump.  Translation between machine-readable and
475   human-readable should be straightforward, if meta-data is available.
476
477 This leads to a human-readable dialect of the xdump language.
478
479
480 Human-Readable xdump Language
481
482 Fundamental difference to basic, machine-readable xdump: the rigid
483 single space between fields is replaced by the rule known from
484 programming languages: white-space (space and tab) separates tokens
485 and is otherwise ignored.  The space non-terminal is no longer needed.
486
487 Rationale: This allows visual alignment of columns and free mixing of
488 space and tab characters.
489
490 Comments start with "#" and extend to the end of the line.  They are
491 equivalent to a newline.
492
493 Rationale: Follow econfig syntax.
494
495 Tables with a record UID in the leftmost field can be `split
496 vertically' into multiple parts.  Each part must contain the same set
497 of records.  The leftmost field must be repeated in each part.  Other
498 fields may be repeated.  Repeated fields must be the same in all
499 parts.  Naturally, the parts together must provide the same fields as
500 a table that is not split.
501
502 Rationale: This is to let you avoid long lines.  Line continuation
503 syntax would be simpler, but turns out to be illegible.  Requiring
504 record UID is not technically necessary, as counting records works the
505 same whether a table is split or not.  Except humans can't count.
506 Perhaps this should be a recommendation for use rather than part of
507 the language.
508
509 EBNF changes:
510
511 * Header and footer:
512
513     header = "config" identifier newline colhdr newline ;
514     colhdr = { identifier [ "(" ( intnum | identifier ) ")" ] } [ "..." ] ;
515     footer = "/config" newline ;
516
517   If colhdr ends with "...", the table is continued in another part,
518   which shall follow immediately.
519
520   Rationale:
521
522   - The xdump needs to identify itself as human-readable, hence change
523     from "XDUMP" to "config".
524
525   - The timestamp in the header is useless for the applications we
526     have in mind for human-readable xdumps.  The number of records in
527     the footer is of marginal value at best, and a pain for humans to
528     update.
529
530   - The column header is due to the self-containedness requirement.
531     It contains just the essential bit of meta-data: the column names.
532
533 * Symbolic fields:
534
535     field = intnum | flonum | string | symbol | symset ;
536
537   Rationale:
538
539   - Syntax for symbols and sets of symbols is due to the
540     self-containedness requirement.  Machine-readable xdump gets away
541     with just numbers, which have to be decoded using meta-data.
542
543 * Friendlier numbers and strings:
544
545     flonum = ? floating-point in scanf %g format ? ;
546     str-char = "\\" octal-digit octal-digit octal-digit
547              | ? ASCII characters 32..126 except '"' and '\\' ? ;
548
549   Rationale:
550
551   - Machine-readable floating-point syntax is too rigid.  Accept
552     everything that scanf does.  Could also change intnum to %i
553     format, which accepts octal and hexadecimal in C syntax, but that
554     seems not worth the documentation bother.
555
556   - Machine-readable syntax requires \040 instead of space in strings
557     to allow trivial splitting into fields.  This is unacceptable here
558     due to the legibility requirement, hence the change to str-char.
559
560 * Parse nil as symbol:
561
562     string = '"' { str-char } '"' ;
563
564   Rationale: This is a technicality required to keep the parse
565   unambiguous.
566
567 * Symbols:
568
569     symbol = identifier ;
570     symset = "(" { symbol } ")" ;
571
572   The special symbol "nil" is to be interpreted as null string.
573
574   Rationale:
575
576   - The symbol set syntax is the simplest that could work.  We need to
577     allow space between the symbols for legibility anyway, so why not
578     make it the delimiter.  A stop token is required to find the end
579     of the field, and a start token is useful for distinguishing
580     between symbol and symset.  Bracketing with some kind of
581     parenthesis is an obvious solution.
582
583 The resulting sub-language for records is a superset of
584 machine-readable sub-language for records.
585
586 See src/lib/global/*.config for examples.
587
588
589 Notes on Table Configuration Implementation
590
591 econfig key custom_tables lists table configuration files.  At this
592 time, reading a custom table merges it with the built-in table, then
593 truncates the result after the last record read from the custom table.
594
595 Some of the tables are rather ugly in C, and cumbersome to edit.  We
596 thus moved them to configuration files (src/lib/global/*.config).  The
597 server reads them from builtindir before reading custom tables.
598
599 The code dealing with these files is in src/lib/common/conftab.c.
600
601 Actual work is done by src/lib/common/xundump.c, which accepts both
602 human-readable and machine-readable input.  The parser is not precise;
603 it accepts human-readable syntax even within tables whose header marks
604 them machine-readable.
605
606 Symbolic index values in column headers are not implemented.  They
607 occur in item selector pkg, which is an array indexed by values in
608 symbol table packing.
609
610 Configuration tables contain values that are not meant to be
611 customized.  For instance, meta-data and symbol tables reflect the
612 encoding of C language constructs in the server.  Such selectors are
613 marked (struct castr member ca_dump), so that the code can prohibit
614 changes.
615
616 All tables are checked against meta-data on server startup by
617 ef_verify().  More elaborate checking would be nice, and probably
618 requires additional meta-data.
619
620
621 Appendix: Empire 3 C_SYNC --- A Cautionary Tale
622
623 Clients are just as important as the server, and it's too darn hard to
624 write a good client.  In 1995, Ken Stevens decided to do something
625 about it.
626
627 Ken cast the problem as a data synchronization problem.  Quote C_SYNC
628 RFC 5.1, section `Abstract':
629
630   This is a specification for a new method of synchronizing game data
631   in the Empire client with data in the server.
632
633 and section `Objectives':
634
635   This new mode of communication between the server and the client will
636   be called C_SYNC communication and will satisfy the following 6
637   criterea:
638
639   (1) Output format will be version independent.  So if someone is
640   using an old EmpireToolkit, then it will still work with a newer
641   version of the server.
642
643   (2) Every C_SYNC message will be a self-contained packet.  i.e. the
644   client will not need to depend on previous messages (header messages)
645   to determine the meaning of a C_SYNC message.
646
647   (3) A C_SYNC message will be able to represent any of the
648   player-accessible data that is contained in the server database (e.g.
649   enemy ships, nations).
650
651   (4) Bandwidth will be minimized (i.e. the format will be as
652   concise as possible) while remaining human-readable (i.e. no
653   binary messages).  [Note that data compression may be added at a later
654   date, but if it is added, it will be added on a separate port to
655   maintain backwards compatability.]
656
657   (5) The client will be able to tell the server whether it wants
658   to receive C_SYNC messages and whether these messages can be sent
659   asynchroniously (via "toggle sync" and "toggle async" respectively).
660
661   (6) A portable ANSI C EmpireToolkit will be made available for
662   parsing C_SYNC messages and managing the data they contain.
663
664 C_SYNC worked by hooking into ef_write() & friends so it could
665 `synchronize' the client on game state changes.
666
667 Sounds jolly good, doesn't it?
668
669 Well, it was a failure, and Wolfpack ripped it out right away.  Quote
670 the change log:
671
672   Changes to Empire 4.0.0 - Initial release
673    * Initial Wolfpack release - Long live the Wolfpack!!!!
674 [...]
675    * Removed C_SYNC.  This is done for 2 reasons.  1) None of us like it or
676       wish to support it.  2) We envision a better scheme for doing similar
677       things will come along.
678
679 But *why* did it fail?  Just because Steve McClure hated it?  Nope.
680 C_SYNC failed for several different reasons, each of them bad, but
681 only the last one is truly fundamental.
682
683 a. Lack of a rigorous and complete definition.  The RFC is long on
684    syntax, but short on semantics.  For instance, the unit type was
685    encoded as a number.  Unit characteristics happened to be dumped in
686    an order that matched these numbers, but that wasn't defined
687    anywhere.
688
689 b. Overly complicated syntax.  Trouble with encoding of strings.
690
691 c. Buggy implementation.  Malformed C_SYNC messages, duplicate
692    messages, missing messages, semantically incorrect messages, you
693    name it.
694
695 d. Change of crew before it was finished.  Wolfpack took over and
696    understandable wasn't interested in this half-finished mess.
697
698 None of the above is a fundamental, inherent flaw of the idea.  The
699 next one is more serious:
700
701 e. It failed to achieve objective (4), and therefore slowed down
702    clients too much to be of use in real-time combat.  When you fired
703    from a bunch of ships, C_SYNC would push complete records for all
704    the ships and the target to you.  Most of that data is redundant.
705
706    That's because C_SYNC didn't transmit state changes, it
707    resynchronized state, and the pieces of state it could transmit
708    were too large.
709
710    The network was slower then.  But let's not be complacent.  I/O is
711    slow.  Always was, most likely ever will be.
712
713    Maybe sending the messages out of band (separate TCP stream) would
714    help.  Maybe not.
715
716 And here comes the killer:
717
718 f. The data to sync is not readily available on the server.
719
720    Yup.  Think about it.  The game state on the server is *not* the
721    same as on the client.  The server grants the client a carefully
722    limited view on certain parts of server game state on certain
723    events.
724
725    To be complete, a machine-readable protocol must disclose as much
726    information as the human-readable output.  Tracking server game
727    state changes cannot do that alone.  For instance, lookout tells
728    you ship#, owner and location.  That event does not trigger any
729    state change on the server!
730
731    To be correct, a machine-readable protocol must disclose no more
732    information than the human-readable output.  When you observe a
733    server game state change, you can only guess what event triggered
734    it, and what it disclosed to which player.  You're stuck with
735    conservative assumptions.  That's the death knell for completeness.
736    Correct assumptions will be non-obvious, so correctness is
737    non-obvious, too, hence hard to achieve and maintain.
738
739    Bottom line: tracking server state change cannot support a complete
740    client protocol for hard theoretical reasons, and I believe it
741    cannot support a correct one for practical reasons.
742
743 Oddly enough, people criticized C_SYNC for all the flaws it had (and
744 some it hadn't), except for f.
745
746 What now?  Throw up our hands in despair and give up?  Nah.  Ken tried
747 a shortcut, and it didn't work.  That doesn't mean there's no way at
748 all.  I believe the only way to get this done right is by tracking
749 *events*.  Whenever something is printed to a player, be it live
750 connection or telegram, we need to transmit precisely the same
751 information in machine-readable form.  Much more work.
752
753 xdump shares valuable ideas with C_SYNC, e.g. using selector
754 meta-data.  It is, however, much more modest in scope.  We're pretty
755 sure we can get it right and get it done in a reasonable time frame.