[##:##] Command : xdump <TYPE|NUMBER> <RECORDS>
[##:##] Command : xdump meta <TYPE|NUMBER>
The xdump command displays information on game configuration and state in machine readable format. It is intended for use by clients and tools. This info page gives an overview; see doc/xdump in the source distribution for complete documentation.
Game configuration and state consists of a number of tables or files. xdump shows only things that are \*(fIcertainly\*(fP visible to you: sectors you own, ship types known, etc.
The output of xdump is a table consisting of a header line, the table body and a footer line.
The header line is of the form XDUMP <TYPE> <TIMESTAMP>. <TYPE> identifies the dump. The timestamp permits incremental dumps (see below).
The body consists of records; one record per line. A record consists of fields separated by a space. All records have the same number of fields. Fields match records in the table's meta-table (see below).
A field is either in integer, floating-point number or string format. In no case does it contain space or newline. All fields in the same column have the same format.
Integer fields are in decimal; they can be parsed by scanf %d. Conversely, if that succeeds and consumes the complete field, it's an integer field.
Floating-point fields can be parsed by scanf %g (or equivalents %e, %f). Conversely, if that succeeds, it's a floating-point field.
String fields are in C syntax. Funny characters including space, newline and double-quote are shown as octal escape sequences. Example: "gold\040mine". If a field starts with a double-quote, it's a string field.
We might decide to support more C escape sequences, but never \\\(dq.
Some fields can contain null strings. A null string is the three letters nil. If a field contains nil, it's a string field.
Each table has a meta-table, which defines format and meaning of its
fields. To show the meta-table for <TYPE>, use
[##:##] Command : xdump meta <TYPE>
All meta-tables share the same meta-meta-table, which is its own
meta-table. The command to show it is
[##:##] Command : xdump meta meta
Fields correspond to selectors used in Empire conditionals (see info Selector), and they use the same names. Naturally, xdump shows fields corresponding to deity-only selectors only to deities.
The command to display table <TYPE> is
[##:##] Command : xdump <TYPE> <RECORDS>
Argument <RECORDS> selects which records to show, in common Empire syntax for the kind of things in that table. * always shows the complete table.
To dump sector -22,2, for example, you can use:
[##:##] Command : xdump sect -22,2
This dumps all ships with mobility in fleet a:
[##:##] Command : xdump ship a ?mobil>0
This dumps all sectors changes after timestamp 1141068862:
[##:##] Command : xdump sect * ?timestamp>1141068862
Use this with a value one less than the timestamp in the xdump header to get everything that changed since that xdump (incremental dump).
We may still extend the syntax to select fields to be shown.
The table table is the table of (non-meta-)tables. It contains table names and numbers. xdump accepts table numbers as well as names. Table numbers may differ between server versions.
Still missing are game state files power, map, bmap; the list of commands; foreign levels, contact information, mortal access to sector selector mines, ship selectors xbuilt, ybuilt, trade selectors xloc, yloc, commodity selectors xbuy, ybuy, xsell, ysell. Some information is not yet available in human-readable form: the lost file, sect-chr selector nav, ship and land plague status (deity only), plane theta (governs satellite movement), trade selectors xloc, yloc, commodity selectors xbuy, ybuy. Incremental dump doesn't work after importing news with the empdump utility.
xdump evolves along with the server. Clients should cope gracefully with new tables and fields. We try to avoid incompatible changes, but they are occasionally necessary to make progress.
See also : dump , ldump , ndump , pdump , sdump , lost , show , version , Communication , LandUnits , Planes , Sectors , Ships