Untitled

Ground Zero Format

Version 1.1
Author Tim Jones, Joachim Heck
Date 6th June 1998
Status Approved

Introduction

Scope

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.

  1. 7-Bit ASCII human readable i.e. something useful to someone playing a PBEM game without any additional software.
  2. It should be able to describe a game which uses any of the standard rules found in GZG products
  3. Defined clearly enough to permit its use by a variety of possible programs, for map drawing, tactical analysis, producing 3D ray-traced animation's, etc. for PBEM/Internet and at the board play.
  4. It should directly support, or be extendible enough to support a reasonable set of house rules (e.g. Newtonian mechanics, or B5 interceptors).
  5. Human writeable, i.e. a PBEM referee could produce a report manually if need be.
  6. Machine writeable, i.e. a PBEM referee could have some snazzy tool for generating his turn reports.

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.

Communication Framework

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.

Notational Conventions

This specification uses an augmented Backus-Naur Form (BNF) notation. The differences from standard BNF involve naming rules and indicating repetition and local alternatives.

Rule Naming

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"

*rule: Repetition

The character "*" preceding an element indicates repetition. The full form is:

<l>*<m>element

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.

#rule: Lists

A construct "#" is defined, similar to "*", as follows:

<l>#<m>element

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.

; Comments

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.

 

Lexical Analysis Of Files

General Description

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:

gzf-file = *block
block = *field CRLF
field = field-name ":" [field-body] CRLF

Long Fields

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.

Structure Of Fields

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.

Unstructured Field-Bodies

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.

Structured Field-Bodies

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.

Example

        Damage-Track: XXXX 0000 0000  # 4 pts from HMS Huron
        Firing-Arcs: F P S
        Movement: 1P +1

Case Sensitivity

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.

Field Definitions

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 ":">
field-body = field-body-contents
[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>

Example

        Version: 1
        Profile: FT

Typographic Conventions

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.

Example

        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.

Example

        Status: Destroyed # acceptable
        Status: DESTROYED # not acceptable

Block Identification

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.

 

Lexical Tokens

The following rules are used to define an underlying lexical analyzer, which feeds tokens to higher level parsers.

      ;Octal Decimal
CHAR = <any ASCII character> ;0-177 0.-127
ALPHA = <any ASCII alphabetic character> ;101-132
;41-172
65.- 90
97.-122
DIGIT = <any ASCII decimal digit> ;60- 71 48.- 57
CTL = <any ASCII control character and DEL> ;0- 37
;177
0.- 31
127
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
<#> = <ASCII hash> ;43 35
CRLF = CR LF    
LWSP-char = SPACE / HTAB ; semantics = SPACE
linear-white-space = 1*([CRLF] LWSP-char) ; semantics = SPACE
; CRLF => folding
delimiters = linear-white-space / comment    
text = *<any CHAR, except <#> including bare CR and bare LF, but not including CRLF> ; unstructured
; atoms not recognised
atom = 1*<any CHAR excepting <#>, SPACE and CTL's ; structured field
comment = (1*<#> [text] CRLF) ; can be embedded anywhere

 

GZF Specification

file = header-block *profile-block ; header then profile blocks
header-block = header-fields *CRLF ; block of header specific
; fields terminated by null line
profile-block = *profile-field *CRLF ; block of profile specific
; fields terminated by null line
header-fields = content-type
content-version
profile-type
profile-version
*optional-field
; 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  
format = "gzf"  
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  
optional-field = "Author" ":" text /
"Date" ":" date-time /
extension-field /
user-defined-field
; 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
month = "Jan" / "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
year = 4DIGIT ; 1998
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>  

Example

        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