Empire is designed as a smart server with dumb clients. An Empire
client need to know nothing about the game. Even telnet would do. In
-fact, emp_client is little more than a slightly specialized telnet.
+fact, empire-client is little more than a slightly specialized telnet.
In such a design, presentation is in the server, and it is designed
for human consumption. Ideally, presentation and logic are cleanly
use '-' in meta-identifiers and omit the concatenation symbol ','.
table = header { record } footer ;
- header = "XDUMP" space [ "meta" space ] name space timestamp newline ;
- name = name-chr { name-chr } ;
- name-chr = ? ASCII characters 33..126 ? ;
+ header = "XDUMP" space [ "meta" space ]
+ identifier space timestamp newline ;
+ identifier = id-chr { id-chr } ;
+ id-char = ? ASCII characters 33..126 except '"#()<>=' ? ;
timestamp = intnum ;
footer = "/" number newline ;
record = [ fields ] newline ;
Semantics:
-* The table name in the header is one of the names in xdump table.
+* The table identifier in the header is one of the names in xdump table.
* The timestamp increases monotonically. It has a noticeable
granularity: game state may change between an xdump and the next
data. So we start with that:
[14:640] Command : xdump meta meta
- XDUMP meta meta 1139555204
+ XDUMP meta meta 1303706667
"name" 3 4 0 -1
- "type" 5 4 0 32
- "flags" 6 12 0 33
- "len" 8 4 0 -1
- "table" 9 4 0 -1
+ "type" 4 4 0 34
+ "flags" 5 12 0 33
+ "len" 7 4 0 -1
+ "table" 8 4 0 27
/5
To interpret this table, we have to know the field names and their
for table IDs and to encode symbols are none of the client's business.
The encoding doesn't normally change within a game. Except when the
-game is migrated to a sufficiently different server. That's a
-difficult and risky thing to do, especially as there are no tools to
-help with migrating (yet). Clients may wish to provide for such
-changes anyway, by decoupling the client's encoding from the server's,
-and dumping fresh meta-data on login. Incremental meta-data dump
-would be nice to have.
+game is migrated to a sufficiently different server. That's a rare
+event. Clients may wish to provide for such changes anyway, by
+decoupling the client's encoding from the server's, and dumping fresh
+meta-data on login. Incremental meta-data dump would be nice to have.
So we don't know how symbol type and symbol set flags are encoded. To
decode them, we need their symbol tables. However, we need flags and
its meta-data:
[31:640] Command : xdump meta table
- XDUMP meta table 1139556230
- "uid" 9 0 0 26
+ XDUMP meta table 1303706678
+ "uid" 8 0 0 27
"name" 3 4 0 -1
/2
Because xdump table is referenced from elsewhere (xdump meta meta
field table), the leftmost field must contain the key. Thus, the
leftmost field's meta-data field table must be the table ID of xdump
-table itself. Let's try it:
+table itself. Indeed, its value matches the one we got in xdump meta
+meta. Let's try to dump the table:
- [30:640] Command : xdump 26 *
- XDUMP table 1139556210
+ [30:640] Command : xdump 27 *
+ XDUMP table 1303706692
0 "sect"
1 "ship"
[...]
9 "nat"
[...]
- 16 "sect-chr"
- 17 "ship-chr"
+ 19 "sect-chr"
+ 20 "ship-chr"
[...]
- 26 "table"
+ 27 "table"
[...]
- /45
+ /49
It worked!
Now dump the two symbol tables we postponed. Because xdump accepts
table IDs as well as names, we don't have to know their names:
- [14:640] Command : xdump meta 32
- XDUMP meta meta-type 1139555298
- "value" 9 4 0 -1
- "name" 3 0 0 -1
+ [14:640] Command : xdump meta 34
+ XDUMP meta meta-type 1303706718
+ "value" 8 4 0 -1
+ "name" 3 4 0 -1
/2
- [15:640] Command : xdump 32 *
- XDUMP meta-type 1139555826
+ [15:640] Command : xdump 34 *
+ XDUMP meta-type 1303706737
1 "d"
2 "g"
3 "s"
/14
[15:640] Command : xdump meta 33
- XDUMP meta meta-flags 1139555303
- "value" 9 4 0 -1
- "name" 3 0 0 -1
+ XDUMP meta meta-flags 1303706753
+ "value" 8 4 0 -1
+ "name" 3 4 0 -1
/2
[24:640] Command : xdump 33 *
- XDUMP meta-flags 1139555829
+ XDUMP meta-flags 1303706765
1 "deity"
2 "extra"
4 "const"
type d (const) 0 meta-type
flags d (bits const) 0 meta-flags
len d (const) 0
- table d (const) 0
+ table d (const) 0 table
Dumping the remaining tables is easy: just walk the table of tables.
Here's the first one:
[36:640] Command : xdump meta 0
- XDUMP meta sect 1139556498
- "owner" 6 0 0 9
- "xloc" 10 0 0 -1
- "yloc" 11 0 0 -1
- "des" 4 0 0 16
+ XDUMP meta sect 1303706822
+ "owner" 5 0 0 9
+ "xloc" 9 4 0 -1
+ "yloc" 10 4 0 -1
+ "des" 4 0 0 19
[...]
- /69
+ /78
A whole load of tables referenced! Only one of them (not shown above)
is a symbol table.
expressed in meta-data (yet).
Let's stop here before this gets too long and boring. Experiment
-yourself! Check out example Perl code src/xdump.pl.
+yourself! Check out example Perl code scripts/xdump.pl.
Analysis of xdump as Configuration File Format
- No comment syntax.
* Each table is self-contained. You don't have to look into other
- tables to make sense of it.
+ tables to make sense of it.
This conflicts with xdump's separation of data and meta-data. You
need the table's meta-data to identify fields, and the referenced
* Header and footer:
- header = "config" name newline colhdr newline ;
+ header = "config" identifier newline colhdr newline ;
colhdr = { identifier [ "(" ( intnum | identifier ) ")" ] } [ "..." ] ;
footer = "/config" newline ;
update.
- The column header is due to the self-containedness requirement.
- It contains just the essential bit of meta-data: the column name.
+ It contains just the essential bit of meta-data: the column names.
* Symbolic fields:
enemy ships, nations).
(4) Bandwidth will be minimized (i.e. the format will be as
- concise as possible) while remaining human readable (i.e. no
+ concise as possible) while remaining human-readable (i.e. no
binary messages). [Note that data compression may be added at a later
date, but if it is added, it will be added on a separate port to
maintain backwards compatability.]
And here comes the killer:
-f. The data to sync is not readily available the server.
+f. The data to sync is not readily available on the server.
Yup. Think about it. The game state on the server is *not* the
same as on the client. The server grants the client a carefully
limited view on certain parts of server game state on certain
events.
- To be complete, a machine readable protocol must disclose as much
- information as the human readable output. Tracking server game
+ To be complete, a machine-readable protocol must disclose as much
+ information as the human-readable output. Tracking server game
state changes cannot do that alone. For instance, lookout tells
you ship#, owner and location. That event does not trigger any
state change on the server!
- To be correct, a machine readable protocol must disclose no more
- information than the human readable output. When you observe a
+ To be correct, a machine-readable protocol must disclose no more
+ information than the human-readable output. When you observe a
server game state change, you can only guess what event triggered
it, and what it disclosed to which player. You're stuck with
conservative assumptions. That's the death knell for completeness.
all. I believe the only way to get this done right is by tracking
*events*. Whenever something is printed to a player, be it live
connection or telegram, we need to transmit precisely the same
-information in machine readable form. Much more work.
+information in machine-readable form. Much more work.
xdump shares valuable ideas with C_SYNC, e.g. using selector
meta-data. It is, however, much more modest in scope. We're pretty