Difference between revisions of "EDF"

From Eternity Wiki
Jump to: navigation, search
(Editing Reference)
(Implementation: Eternity never loads modules as "default fallbacks" any longer so that section has been removed.)
Line 219: Line 219:
 
* All identifiers containing ANY non-alphanumeric character excepting non-leading underscores (ex: $ is reserved).  
 
* All identifiers containing ANY non-alphanumeric character excepting non-leading underscores (ex: $ is reserved).  
  
For maximum safety, it is recommended that you develop a consistent and unique naming scheme for objects you create yourself. This has the positive side effect, of improving the ability of your EDF patches to combine with those of others.
+
For maximum safety, it is recommended that you develop a consistent and unique naming scheme for objects you create yourself. This has the positive side effect, of improving the ability of your EDF patches to combine with those of others.
 
 
===Default fallback===
 
As a failsafe to allow old EDF modifications to continue working, EDF is now capable of loading default modules individually when it determines there are zero definitions of certain sections.
 
  
 
==Verbose EDF logging==
 
==Verbose EDF logging==

Revision as of 17:09, 8 May 2011

EDF, Eternity Definition File, is a language used to define and modify monsters, decorations, sounds, text strings, menus, terrain types, and other data in Eternity Engine.

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++. Also, the equal sign (as a standalone operator) used to connect keywords with values is no longer required. 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. To reduce cluttering, examples and definitions throughout this wiki will be written without the equal operator.

Value types

Fields in EDF can take character string, heredoc, numeric values or lists of values.

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\''
    }

Line Continuation:

Starting with Eternity Engine v3.31 Delta, line continuation can be used to split quoted strings across multiple lines. The syntax for doing this is demonstrated in the following example:

    frame S_MYFRAME
    {
       cmp = "TROO|A|*|6 \
              TroopAttack|@next"
    }

The "\" character, when followed immediately by a line break, signifies that line continuation should be triggered. Whitespace before the line continuation will be included in the string, but any spaces or tabs at the beginning of the next line will NOT be included (this is the same as line continuation in BEX files). This allows the following continued parts of the string to be arbitrarily indented for purposes of beautification. A string can be split across any number of lines in this fashion.

NOTE: Simply adding "\" will not result in a newline character even if the continued string appears multiline in the EDF file. For text that is supposed to be multiline, use heredocs instead.

Heredocs

EDF supports heredocs, which are multi-line strings. A heredoc is delimited by @" and "@, and can be placed interchangeably with a string, especially where more lines are needed. Heredocs are commonly used where non-EDF code is implemented, such as in DECORATE-style state definition or sound sequencing. Note: in heredocs, any character is taken into account, such as whitespaces at the beginning of a line. It is up to the interpreter reading the contents of the heredoc to remove extraneous whitespaces, and such characters will appear where literal text is to be written.

Numbers

Most non-string fields in EDF are numbers, either integer or floating-point. Starting with EDF 1.1, decimal, octal, and hexadecimal integers will be accepted in all number fields. Octal numbers start with a zero, and hexadecimal numbers start with the sequence 0x -- Examples:

    # this is a normal, decimal number (base 10)
    spriteframe = 16
    ...
    # this is an octal number (base 8)
    spriteframe = 020
    ...
    # this is a hexadecimal number (base 16)
    spriteframe = 0x10

Floating-point numbers must have a decimal point in them, as in "20.0". Floating-point numbers are always base 10.

Value lists

Fields can take multiple values, enclosed in curly braces and separates by commas. The spritenames block includes such an example, or other situations such as non-heredoc sound sequences.

Note: commas are not interchangeable with semicolons, and are used only to separate values inside lists, whereas semicolons are simple substitutes to white space in general parts of the code.

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
       
    */

Implementation

Loading EDF

By default, Eternity loads the EDF file from the relative path: base\root.edf. The root file can be substituted as follows, either from an external file or a WAD lump:

  • To load an EDF root from a WAD file, the name of the root EDF lump must be "EDFROOT".
  • To include an EDF file from the command line, use the -edf parameter. For example: eternity -edf c:\blah\root.edf
  • A GFS file can specify the root EDF file with the edffile keyword. Only one EDF file can be specified in a GFS. If -edf is used when a GFS is loaded, the command-line parameter will take precedence. See the GFS documentation for further information.

Unless the intention is to redefine the entire game structure, the overriding root EDF file must contain a command at the top to include the base\root.edf file, by using this function: stdinclude("root.edf"). Note that it is possible to load several wads containing EDFROOT; they will be processed additively.

Including files

Use of include files is critical for several purposes. First, it's unorganized and difficult to maintain EDF files when everything is put haphazardly into one file.

To include a file or wad lump normally, with a path relative to the current file doing the inclusion, use the include function, like in these examples:

# include examples

include("myfile.edf")
include("../prevdir.edf");  # remember, semicolons are purely optional

This example would include "myfile.edf" from the same directory that the current file is in, and "prevdir.edf" from the parent directory. It is important to note that this function can only include files when called from within a file, and it can only include WAD lumps when called from within a WAD lump. This restriction is necessary due to how the complete path of the included file must be formed.

In order to remain compatible with future versions of Eternity, and to greatly reduce EDF file sizes, include the standard, default EDF files into your own. To include the files from Eternity's base directory, use the stdinclude function:

stdinclude("root.edf")

Note: to ensure backward and forward compatibility, do not include other EDF files from the base directory than root.edf.

Include statements may only be located at the topmost level of an EDF file, and not inside any section.

The userinclude function allows the optional inclusion of a file from Eternity's base folder. This function is identical to stdinclude, except that it will test to see if the file exists beforehand, and if it does not, no error will occur. This function is NOT for use by EDF editors in projects. This function is intended for end-user modification of EDF settings, including but not limited to the custom user menu. Example:

userinclude("user.edf")

This example can be found in Eternity's root.edf, where it exists to include the optional user-defined "user.edf" file. You should never attempt to overwrite the user.edf file with one from your own project, as this is outside the scope of its purpose and will be offensive to the end user.

Including lumps

This lumpinclude function includes a wad lump when called from either a file or a lump. The lump named must exist, or an error will occur. The name must also be no longer than eight characters. Case of the lump name will be ignored as usual. Example:

lumpinclude("MYEDFLMP")

Another function, include_prev() may be encountered in EDF files or lumps for older versions of Eternity. It has been deprecated and has no effect.

Note: including a lump or file several times is safe.

Including BEX files(deprecated)

It is possible to include BEX files by using:

bexinclude("file.bex")

but it is recommended to use the DEHACKED lump or GFS files rather than EDF.

Base EDF files

This section explains the contents of each of the standard default EDF modules. Note that some are game-dependent and are in consequence included in their respective folders, as well as the base folder for the common features.

  • cast.edf -- contains castinfo (Doom 2 cast call) definitions
  • fonts.edf -- contains font definitions -- game dependent
  • frames.edf -- contains frame definitions -- game dependent
  • misc.edf -- contains boss_spawner_types and some Heretic-specific string blocks
  • player.edf -- contains skin and playerclass definitions
  • root.edf -- includes all other modules
  • sounds.edf -- contains sound and soundsequence definitions -- game dependent
  • sprites.edf -- contains spritenames and pickupitem definitions
  • sounds.edf -- contains sound definitions
  • terrain.edf -- contains splash, terrain, floor definitions
  • things.edf -- contains thingtype and damagetype definitions
  • user.edf -- optional user-defined EDF file which may contain any definitions

Click on any of the links for reference on how to use the specific blocks.

Lumps besides EDFROOT that are automatically loaded

Eternity can load other EDF lumps, besides EDFROOT. Previously, they were dedicated to specific blocks, but now can be used for any purpose. They don't need to be explicitly included from EDFROOT, but it is no danger in doing so.

  • ESTRINGS
  • ETERRAIN
  • EMENUS
  • ESNDSEQ
  • ESNDINFO
  • EFONTS

Reserved identifiers

This section describes classes of identifiers (such as thing, frame, and sound mnemonics) which are considered reserved by the Eternity Engine. You should avoid using any identifier in the following classes for objects which you define yourself. Failure to do so could result in incompatibility of your project with future versions of the Eternity Engine due to conflicts with newly added game engine features.

  • All identifiers beginning with _ (underscore)
  • All identifiers beginning with EE or ee (this prefix means "Eternity Engine" and is therefore reserved for use by the source port's authors only).
  • All identifiers containing ANY non-alphanumeric character excepting non-leading underscores (ex: $ is reserved).

For maximum safety, it is recommended that you develop a consistent and unique naming scheme for objects you create yourself. This has the positive side effect, of improving the ability of your EDF patches to combine with those of others.

Verbose EDF logging

Eternity includes a verbose logging feature in the EDF processor that allows a view of more detailed information on what is occuring while EDF is being processed. This can help nail down the location of any errors or omissions. To enable verbose EDF logging, use the command-line parameter -edfout. This will cause Eternity to write an "edfout##.txt" log file in its current working directory, where ## is a unique number from 0 to 99.

Tutorials

Editing Reference