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 just as 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
Except for commands that actually don't do anything. There's a useful
class of such commands: commands to show game configuration and state
without altering it. The only game rules involved are those that
-govern who gets to see what. Ensuring that those are satisfied is
+govern who gets to see what. Ensuring that those are obeyed is
tractable.
Empire has had one such command since the beginning: dump. Empire
perhaps, different server versions. We will see below that xdump
isn't quite sufficient for that, but it's a start.
-If you can import game state, you can import game configuration, or in
-other words: customize your game. As we will see, configuration files
-have different requirements, which xdump doesn't satisfy without some
+Means to import game configuration let you customize your game without
+recompiling the server. As we will see, configuration files have
+different requirements, which xdump doesn't satisfy without some
extensions.
If game import code can edit everything, then a deity command capable
* Output is self-contained; symbol encoding is explicit.
-* KISS: keep it simple, keep it stupid.
+* KISS: Keep it simple, stupid.
Non-requirements:
Some integer fields are actually keys in other tables. For instance,
ship field type is a key in the table of ship types ship-chr, and
-plane field ship is a key in the ship table. Key value -1 is special:
-it's a null key. Meta-data encodes these table reference just like
-for symbols: the meta-data has the ID of the referenced table, and
-that table has the key in the leftmost column. Obviously, that
-leftmost column is a table key as well, referencing the table itself.
+plane field ship is a key in the ship table. Key -1 is special: it's
+a null key. Meta-data encodes these table reference just like for
+symbols: the meta-data has the ID of the referenced table, and that
+table has the key in the leftmost column. Obviously, that leftmost
+column is a table key as well, referencing the table itself.
A table with its key in the leftmost column can be dumped partially.
Without such a key, you need to count records to find the record
index, and that works only if you can see a prefix of the complete
table.
-The special table "ver" collects all scalar configuration parameters
-in a single record. It does not occur in the table of tables.
-
Syntax of xdump command
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-char1 { id-char } ;
+ id-char1 = ? ASCII letter ? ;
+ id-char = ? ASCII characters 33..126 except '"#()<>=' ? ;
timestamp = intnum ;
footer = "/" number newline ;
record = [ fields ] newline ;
parse' requirement
* Space is to be taken literally: a single space character. Not a
- non-empty sequence of whitespace.
+ non-empty sequence of white-space.
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
- "d", field uses intnum syntax
- "g", field uses flonum syntax
- "s", field uses string syntax
- - "c", field uses string syntax
+ - "c", field uses string syntax (only until version 4.3.33)
* flags: The field's flags, a symbol set. Flags are:
- "deity", field visible only to deities
- - "extra", field not to be dumped
- - "const", field cannot be changed (see xundump below)
- "bits", field is a symbol set, field type must encode symbol "d",
field table must not be -1.
+ - "hidden", field value is masked for contact when option HIDDEN is
+ enabled. Masked values are replaced by -1.
* len: If non-zero, then the record encodes an array with that many
- elements. If field type encodes symbol "c", it is a character
- array, which is dumped as a single string field. Else, the array is
- dumped as len fields.
+ elements. The array is dumped as len fields.
+
+ Only until version 4.3.33: if field type encodes symbol "c", it is a
+ character array, and is dumped as a single string field.
* table: Key for xdump table. Unless -1, it defines the table
referenced by the field value. Field type must encode symbol "d"
for another table (new struct castr member ca_table). The selector
code doesn't use that, yet.
-* Selector flag NSC_EXTRA to flag redundant selectors, so that xdump
- can ignore them.
+* Redundant selectors can be marked so that xdump ignores them (new
+ struct castr member ca_dump).
Meta-data is in empfile[] (table meta-data), src/lib/global/nsc.c
(selector meta-data), src/lib/global/symbol.c (symbol tables). The
its meta-data, and to make sense of that table, we need meta-meta
data. So we start with that:
- [14:640] Command : xdump meta meta
- XDUMP meta meta 1139555204
- "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
+ [3:640] Command : xdump meta meta
+ XDUMP meta meta 1466920477
+ "name" 3 0 0 -1
+ "type" 1 0 0 33
+ "flags" 1 8 0 32
+ "len" 1 0 0 -1
+ "table" 1 0 0 26
/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
know, namely the table of tables. Let's dump that next, starting with
its meta-data:
- [31:640] Command : xdump meta table
- XDUMP meta table 1139556230
- "uid" 9 0 0 26
- "name" 3 4 0 -1
+ [3:640] Command : xdump meta table
+ XDUMP meta table 1466920477
+ "uid" 1 0 0 26
+ "name" 3 0 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
+ [5:640] Command : xdump 26 *
+ XDUMP table 1466920477
0 "sect"
1 "ship"
[...]
- 9 "nat"
+ 8 "nat"
[...]
- 16 "sect-chr"
- 17 "ship-chr"
+ 18 "sect-chr"
+ 19 "ship-chr"
[...]
26 "table"
[...]
- /45
+ /48
-It worked! Mind that the special table "ver" is not in the table of
-tables.
+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
+ [5:640] Command : xdump meta 33
+ XDUMP meta meta-type 1466920477
+ "value" 1 0 0 -1
"name" 3 0 0 -1
/2
- [15:640] Command : xdump 32 *
- XDUMP meta-type 1139555826
+ [6:640] Command : xdump 33 *
+ XDUMP meta-type 1466920477
1 "d"
2 "g"
3 "s"
- 4 "d"
- 5 "d"
- 6 "d"
- 7 "d"
- 8 "d"
- 9 "d"
- 10 "d"
- 11 "d"
- 12 "d"
- 13 "g"
- 14 "c"
- /14
-
- [15:640] Command : xdump meta 33
- XDUMP meta meta-flags 1139555303
- "value" 9 4 0 -1
+ /3
+
+ [7:640] Command : xdump meta 32
+ XDUMP meta meta-flags 1466920477
+ "value" 1 0 0 -1
"name" 3 0 0 -1
/2
- [24:640] Command : xdump 33 *
- XDUMP meta-flags 1139555829
+ [7:640] Command : xdump 32 *
+ XDUMP meta-flags 1466920477
1 "deity"
- 2 "extra"
- 4 "const"
8 "bits"
- /4
+ 16 "hidden"
+ /3
We now have complete meta-meta information:
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
+ [7:640] Command : xdump meta 0
+ XDUMP meta sect 1466920477
+ "owner" 1 0 0 8
+ "xloc" 1 0 0 -1
+ "yloc" 1 0 0 -1
+ "des" 1 0 0 18
[...]
- /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
Fundamental difference to basic, machine-readable xdump: the rigid
single space between fields is replaced by the rule known from
-programming languages: whitespace (space and tab) separates tokens and
-is otherwise ignored. The space non-terminal is no longer needed.
+programming languages: white-space (space and tab) separates tokens
+and is otherwise ignored. The space non-terminal is no longer needed.
Rationale: This allows visual alignment of columns and free mixing of
space and tab characters.
Rationale: Follow econfig syntax.
-Tables with a record uid in the leftmost field can be `split
+Tables with a record UID in the leftmost field can be `split
vertically' into multiple parts. Each part must contain the same set
of records. The leftmost field must be repeated in each part. Other
fields may be repeated. Repeated fields must be the same in all
parts. Naturally, the parts together must provide the same fields as
a table that is not split.
-Rationale: This is the cure for long lines. Line continuation would
-be simpler, but turns out to be illegible. Requiring record uid is
-not technically necessary, as counting records works the same whether
-a table is split or not. Except humans can't count. Perhaps this
-should be a recommendation for use rather than part of the language.
+Rationale: This is to let you avoid long lines. Line continuation
+syntax would be simpler, but turns out to be illegible. Requiring
+record UID is not technically necessary, as counting records works the
+same whether a table is split or not. Except humans can't count.
+Perhaps this should be a recommendation for use rather than part of
+the language.
EBNF changes:
* Header and footer:
- header = "config" name newline { colhdr } newline ;
- colhdr = identifier [ "(" ( intnum | identifier ) ")" ] [ "..." ] ;
+ header = "config" identifier newline colhdr newline ;
+ colhdr = { identifier [ "(" ( intnum | identifier ) ")" ] } [ "..." ] ;
footer = "/config" newline ;
If colhdr ends with "...", the table is continued in another part,
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:
The resulting sub-language for records is a superset of
machine-readable sub-language for records.
-
See src/lib/global/*.config for examples.
-Human-readable xdump still has its shortcomings:
-
-* Symbolic references work only with symbol tables. Consider sect-chr
- selector prd, which is a key for table product. xdump should
- support use of product selector sname values as keys. Same for
- product selectors ctype and type, which should support item selector
- mnem values as keys.
-
-* item selector pkg is an array indexed by values in symbol table
- packing. The column header should support symbolic index values
- rather than numbers.
-
Notes on Table Configuration Implementation
it accepts human-readable syntax even within tables whose header marks
them machine-readable.
+Symbolic index values in column headers are not implemented. They
+occur in item selector pkg, which is an array indexed by values in
+symbol table packing.
+
Configuration tables contain values that are not meant to be
customized. For instance, meta-data and symbol tables reflect the
-encoding of C language constructs in the server. Selector flag
-NSC_CONST marks them, so that the code can prohibit changes.
+encoding of C language constructs in the server. Such selectors are
+marked (struct castr member ca_dump), so that the code can prohibit
+changes.
All tables are checked against meta-data on server startup by
ef_verify(). More elaborate checking would be nice, and probably
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
projects / empserver / blobdiff