EDF

From Eternity Wiki
Revision as of 16:54, 5 December 2007 by Esselfortium (talk | contribs) (started working on the page, taking relevant stuff from the EE docs and formatting it for the wiki.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

EDF, which stands for Eternity Definition Files, is a new data specification language that allows dynamic definition of sprites, thing types, frames, and other previously internal data.

EDF supercedes DeHackEd, and should become the preferred method for "exe" editing in the future. However, EDF retains features that allow DeHackEd compatibility, and DeHackEd patches may be loaded over EDF, and even have access to "new" things and frames that are defined by it.

Each section of this page deals with one of the EDF constructs, as well as showing their locations in the default EDF files. However, user-made EDF files can, with a few caveats, contain these structures in any arrangement of files and in any order. User EDF files do not need to use the same names or arrangements as the defaults, and they should NEVER be intended to overwrite the Eternity Engine's default files, unless they are being provided with a customized distribution of the engine itself.

Plans are in place to steadily introduce more features and functionality to EDF in future versions of the Eternity Engine, including most notably, weapon definitions. This documentation will be regularly updated to reflect all changes and additions.

Syntax

EDF is Free-form

Whitespace and token positioning are totally free-form in EDF. In addition, semicolons are discarded as whitespace and can therefore be used to terminate field assignments, lists, etc. as in C or C++. As an example, all of the following are strictly equivalent:

    thingtype w00t { mass = 1000 }
    thingtype w00t
    {
       mass = 1000;
    }
    thingtype
                     w00t
                {
       mass     =
            1000     ;;;;;;
                    }

The usage of a clean and consistent format is encouraged, even though it is not required.

Comments

EDF files can use three forms of comments:

  • # Comments: Like in DeHackEd, this comment type extends to the end of the line.
  • // Comments: An alternate form of single-line comment, equivalent to #.
  • /* */ Comments: This type of comment is multiline, and extends from the opening /* to the first */ found. This type of comment CANNOT be nested. Nested multiline comments will cause a syntax error.

Examples:

    # Single line comment
    // Another single line comment
    /*
    
       This is a multiline comment
       
    */

Strings

Many fields in EDF take strings. Strings, if they do not contain whitespace or any character that needs to be escaped, may be unquoted. Unquoted strings additionally cannot contain any of the following characters: " ' = { } ( ) + , # / ; If any of those characters are found, the unquoted string will be terminated at the last valid character.

Example:

    spritenames += { SPR1, SPR2, SPR3 }

The items SPR1, SPR2, and SPR3 are unquoted strings. Note how the commas serve to separate the items in a list, and therefore do not become part of the strings.

Many fields more or less require quoted strings. Quoted strings must start and end with either single or double quotes (the beginning and ending quote types must match). Quoted strings may contain any character except a line break, including those not allowed in unquoted strings. In addition, quoted strings also support the following escape codes for non-typable characters:

  • \n : Hard line break
  • \t : Tab
  • \b : Backspace
  • \a : Beep (causes a sound when printed to the console)
  • \\ : Literal \ character.
  • \" : Literal ", necessary to use in double-quoted strings only
  • \' : Literal ', necessary to use in single-quoted strings only
  • \0 : Null character
  • \K : Changes text color to "brick" range where supported.
  • \1 : Changes text color to "tan" range where supported.
  • \2 : Changes text color to "gray" range where supported.
  • \3 : Changes text color to "green" range where supported.
  • \4 : Changes text color to "brown" range where supported.
  • \5 : Changes text color to "gold" range where supported.
  • \6 : Changes text color to "red" range where supported.
  • \7 : Changes text color to "blue" range where supported.
  • \8 : Changes text color to "orange" range where supported.
  • \9 : Changes text color to "yellow" range where supported.
  • \N : Changes text color to gamemode "normal" range where supported.
  • \H : Changes text color to gamemode "hilite" range where supported.
  • \E : Changes text color to gamemode "error" range where supported.
  • \S : Toggles text shadowing where supported.
  • \C : Toggles absolute centering of text where supported.

If \ is followed by any other character, the slash is discarded and the next character is treated normally (ie, \d becomes d). Avoid doing this, however, to maintain forward compatibility.

Examples:

    thingtype w00t
    {
       obituary_normal = "w00ts"
       obituary_melee  = 'says \'w00t\
    }