Ground Zero Format
|Author||Tim Jones, Joachim Heck|
|Date||6th June 1998|
This standard specifies a syntax for simple text messages that are sent among computer users, within the framework of a Ground Zero based game, namely Ground Zero Format - GZF. Ground Zero based games are those published by Ground Zero Games - GZG, and include Full/More Thrust - FT, Dirtside 2 - DS2 and Star Grunt 2 - SG2. The standard is intended to support transfer of game state information for PBEM and for computer moderated games.
In addition the format can be used by any computer play-aids available, such as map generation and range charts. The spirit of the standard can also be used to define tool specific data files, so that common low level parsing routines in portable languages such as Java can be used. The format intends to support the following laws of usability in order of importance.
In this context GZF files are viewed as having certain common characteristics and form. However the detailed content will be specific to a given game profile. The game profile is the detailed encoding that each of the GZG games will use, and these will be different as the games are diverse in their setting and rules. For each of the GZG games a separate profile will be published using the conventions laid down in this document. Note: This standard applies only to the format and some of the semantics of file contents. It contains no specification of the information for a specific game profile.
A distinction should be made between what the specification requires and what it allows. Game profiles can be made complex and rich with formally-structured components of information or can be kept small and simple, with a minimum of such information. Also, the standard simplifies the interpretation of differing visual formats in files; only the visual aspect of a information is affected and not the interpretation of information within it. Implementors may choose to retain such visual distinctions.
The formal definition is divided into four levels. The bottom level describes the meta-notation used in this document. The second level describes basic lexical analyzers that feed tokens to higher-level parsers. Next is an overall specification for common characteristics and distinguishing individual fields. Finally, there is definition of the contents of several structured fields.
GZF files consist of lines of text. No special provisions are made for encoding drawings and images. No significant consideration has been given to questions of data compression or to transmission and storage efficiency, and the standard tends to be free with the number of bits consumed. For example, field names are specified as free text, rather than special terse codes. At all stages of the design the laws of usability have been used.
A general structured data blocks framework is used. GZF files consists of some information with a rigid format and content, followed by the main part of the file, with a rigid format but a flexible content, which will be specified in the individual game profiles. The syntax of several fields of the rigidly formatted headers section is defined in this specification; some of these fields must be included in all GZF files. In addition several items common to all game profiles are discussed so that a common look and feel develops.
The syntax that distinguishes between header fields is specified separately from the internal syntax for particular fields. This separation is intended to allow common simple parsers to operate on the general structure of messages, without concern for the detailed structure of individual header fields.
In addition to the fields specified in this document, it is expected that other fields will gain common use. As necessary, the specifications for these extension-fields will be published through the same mechanism used to publish this document through discussion on the FTGZG-L and the GZF-L discussion list. Users may also wish to extend the set of fields that they use privately. Such user-defined fields are permitted and will be ignored by parsers that don't understand them.
The framework constrains document tone and appearance and is primarily useful for most inter game communications over the internet. As the standard is based on RFC#822 which is the basis of the http protocol used by most web servers, the GZF can be used for client server communication of real time game state information.
It is interesting to note that the receiver of a GZF file can exercise an extraordinary amount of control over the files final appearance. The amount of actual control available to file receivers is contingent upon the capabilities of their individual applications.
This specification uses an augmented Backus-Naur Form (BNF) notation. The differences from standard BNF involve naming rules and indicating repetition and local alternatives.
Angle brackets ("<", ">") are not used, in general. The name of a rule is simply the name itself, rather than <name>. Quotation-marks enclose literal text (which may be upper and/or lower case). Certain basic rules are in uppercase, such as SPACE, TAB, CRLF, DIGIT, ALPHA, etc. Angle brackets are used in rule definitions, and in the rest of this document, whenever their presence will facilitate discerning the use of rule names.
|rule1 / rule2: Alternatives
Elements separated by slash ("/") are alternatives. Therefore "foo / bar" will accept foo or bar
|( rule1 rule2): Local Alternatives
Elements enclosed in parentheses are treated as a single element. Thus, "(elem (foo / bar) elem)" allows the token sequences "elem foo elem" and "elem bar elem"
The character "*" preceding an element indicates repetition. The full form is:
indicating at least <l> and at most <m> occurrences of element. Default values are 0 and infinity so that "*(element)" allows any number, including zero; "1*element" requires at least one; and "1*2element" allows one or two.
|[ rule ]: Optional
Square brackets enclose optional elements; "[foo bar]" is equivalent to "*1(foo bar)".
|nrule: Specific Repetition
"<n>(element)" is equivalent to "<n>*<n>(element)"; that is, exactly <n> occurrences of (element). Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three alphabetic characters.
A construct "#" is defined, similar to "*", as follows:
indicating at least <l> and at most <m> elements, each separated by one or more linear-whitespace (HT SPACE) characters. This makes the usual form of lists very easy; a rule such as '(element *(" " element))' can be shown as "1#element". Wherever this construct is used, null elements are allowed, but do not contribute to the count of elements present. That is, "(element),,(element)" is permitted, but counts as only two elements. Therefore, where at least one element is required, at least one non-null element must be present.
Default values are 0 and infinity so that "#(element)" allows any number, including zero; "1#element" requires at least one; and "1#2element" allows one or two.
A semi-colon, set off some distance to the right of rule text, starts a comment that continues to the end of line. This is a simple way of including useful notes in parallel with the specifications.
A GZF file consists of one or more blocks. Blocks are delimited by a null line (i.e., a line with nothing preceding the CRLF). A block contains one or more fields. A field consists of a field-name and an associated field-body. The first field in a block identifies the block-type. Certain blocks can be component-associated with other blocks by immediately following them within the file. The rules of association will be specific to a game profile and specified there. The general structure is expressed as:
|field||=||field-name ":" [field-body] CRLF|
Each field can be viewed as a single, logical line of ASCII characters, comprising a field-name and a field-body. For convenience, the field-body portion of this conceptual entity can be split into a multiple-line representation; this is called folding. The general rule is that wherever there may be linear-white-space (not simply LWSP-chars), a CRLF immediately followed by at least one LWSP-char may instead be inserted. Thus, the single line:-
Description: The first battle in the Iridian vs Culture war took place around the little known system of BigSunNoPlanets.
can be represented as the folded line:
|Description:||The first battle in the Iridian vs Culture war took place around the little known system of BigSunNoPlanets.|
The process of moving from this folded multiple-line representation of a header field to its single line representation is called unfolding. Unfolding is accomplished by regarding CRLF immediately followed by a LWSP-char as equivalent to the LWSP-char.
Note: While the standard permits folding wherever linear-white-space is permitted, it is recommended that structured fields, such as those damage tracks, limit folding to higher-level syntactic breaks. For damage tracks, it is recommended that such folding occur between damage rows, after the separating space.
Once a field has been unfolded, it may be viewed as being composed of a field-name followed by a colon (":"), followed by a field-body, and terminated by a carriage-return/line-feed. The field-name must be composed of printable ASCII characters(i.e., characters that have values between 33. and 126.,decimal, except colon). The field-body may be composed of any ASCII characters, except CR or LF. (While CR and/or LF may be present in the actual text, they are removed by the action of unfolding the field.)
Certain field-bodies of headers may be interpreted according to an internal syntax that some systems may wish to parse. These fields are called structured fields. Examples include fields damage tracks and firing arcs. Other fields, such as Version and Content-Type, are regarded simply as strings of text.
Note: Any field which has a field-body that is defined as other than simply <text> is to be treated as a structured field. Field-names, unstructured field-bodies and structured field-bodies each are scanned by their own, independent lexical analyzers.
For most fields, no structuring is assumed, and they are treated simply as <text> s. Rules of folding apply to these fields, so that such field-bodies which occupy several lines must therefore have the second and successive lines indented by at least one LWSP-char.
To aid in the creation and reading of structured fields, the free insertion of linear-white-space (which permits folding by inclusion of CRLFs) is allowed between lexical tokens. Rather than obscuring the syntax specifications for these structured fields with explicit syntax for this linear-white-space, the existence of another lexical analyzer is assumed. This analyzer does not apply for unstructured field-bodies that are simply strings of <text>, as described above. The analyzer provides an interpretation of the unfolded text composing the body of the field as a sequence of lexical symbols. These symbols are:-
The comments are delimited by CRLF. Atoms are not; they are delimited by linear-white-space. For the purposes of regenerating sequences of atoms exactly one SPACE is assumed to exist, and should be used, between them. Parsers should be tolerant or multiple LWSP characters used as delimiters.
Damage-Track: XXXX 0000 0000 # 4 pts from HMS Huron Firing-Arcs: F P S Movement: 1P +1
In general field-names and field-bodies are case insensitive. This allows some typographic freedom in laying out files, however see Field Style for stylistic conventions. However all field-names and field-bodies with specified contents are spelling sensitive.
These BNF rules show a field meta-syntax, without regard for the particular type or internal syntax. Their purpose is to permit detection of fields; also, they present to higher-level parsers an image of each field as fitting on one line.
|field||=||field-name ":" [ field-body ] CRLF|
|field-name||=||1*<any CHAR, excluding CTLs, SPACE, and ":">|
[CRLF LWSP-char field-body]
|field-body-contents||=||<the ASCII characters making up the field-body, as defined in the following sections, and consisting of atoms or text and comments>|
Version: 1 Profile: FT
To give a consistent look and feel to GZF files it is strongly suggested that the typographic style of field-names is consistent. The preferred style uses hyphenated capitalized words. This is easy on the human eye and follows the same style as http and other common protocols. The captialization rule is easy to remember and apply consistently. This is also the style used in the FT book.
Content-Type: # acceptable Content-type: # not acceptable ContentType: # not acceptable
Where a field-body has a specified contents it is also good practice to follow the typographic conventions in this specification and those of the individual game profiles to achieve a consistent look and feel. The preferred style is again to use capitalized words as it is easy to remember and apply consistently.
Status: Destroyed # acceptable Status: DESTROYED # not acceptable
The first field-name in a block identifies the block-type. This is the only ordering rule on fields within a block. This specification specifies the header block-type for a GZF file all other block-type specifications are the responsibility of the game profiles.
The following rules are used to define an underlying lexical analyzer, which feeds tokens to higher level parsers.
|CHAR||=||<any ASCII character>||;0-177||0.-127|
|ALPHA||=||<any ASCII alphabetic character>||;101-132
|DIGIT||=||<any ASCII decimal digit>||;60- 71||48.- 57|
|CTL||=||<any ASCII control character and DEL>||;0- 37
|CR||=||<ASCII CR, carriage return>||;15||13|
|LF||=||<ASCII LF, linefeed>||;12||10|
|SPACE||=||<ASCII SP, space>||;40||32|
|HTAB||=||<ASCII HT, horizontal-tab>||;11||9|
|<">||=||<ASCII quote mark>||;42||34|
|LWSP-char||=||SPACE / HTAB||; semantics = SPACE|
|linear-white-space||=||1*([CRLF] LWSP-char)||; semantics
; CRLF => folding
|delimiters||=||linear-white-space / comment|
|text||=||*<any CHAR, except <#> including bare CR and bare LF, but not including CRLF>||;
; atoms not recognised
|atom||=||1*<any CHAR excepting <#>, SPACE and CTL's||; structured field|
|comment||=||(1*<#> [text] CRLF)||; can be embedded anywhere|
|file||=||header-block *profile-block||; header then profile blocks|
|header-block||=||header-fields *CRLF||; block of header
; fields terminated by null line
|profile-block||=||*profile-field *CRLF||; block of profile
; fields terminated by null line
|; file protocol
; file protocol version
; profile protocol
; profile protocol version
; others optional
|profile-field||=||field-name ":" [ field-body] CRLF||; profile information|
|content-type||=||"Content-Type" ":" format|
|content-version||=||"Content-Version" ":" version-number|
|version-number||=||1*DIGIT "." 1DIGIT||; 1.1|
|profile-type||=||"Profile-Type" ":" profile|
|profile||=||"FT1" / "FT2" / "FB1" / "FB2" / "FT3" / "DS1" / "DS2" / "SG1" / "SG2"|
|profile-version||=||"Profile-Version" ":" version-number|
":" text /
"Date" ":" date-time /
|; writer of file
; date written
; to be defined
; may be pre-empted
|date-time||=||day date time [zone] year||; Sat Aug 12 02:30:00 PDT 1995|
|day||=||"Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun"|
|date||=||1*2DIGIT month||; 20 Jun|
"Feb" / "Mar" / "Apr" /
"May" / "Jun" /
"Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
|zone||=||"BST" / "EST" / "DST" / "PDT" / "GMT" / "UTC" / <other time zones>||; local time zone eg GMT|
|time||=||2DIGIT ":" 2DIGIT ":" "DIGIT||; 00:00:00: - 23:59:59|
|extension-field||=||<Any field which is defined in a document published as an extension to this specification>|
|user-defined-field||=||<Any field which has not been defined in this specification or published as an extension to this specification; names for such fields must be unique and may be pre-empted by published extensions>|
Content-Type: gzf Content-Version: 1.0 Profile-Type: FT1 Profile-Version: 2.0 Author: Tim Jones Date: Wed 11 Jun BST 02:00:00 1998 # Game profile blocks start here
Feedback on using this standard
Last Updated 8th June 1998