ExtraData

From Eternity Wiki
Revision as of 13:01, 19 April 2010 by Quasar (talk | contribs) (Corrections, updates, and removal of documentation for deprecated features)
Jump to: navigation, search

ExtraData is a new data specification language for the Eternity Engine that allows arbitrary extension of mapthings, lines, and sectors with any number of new fields, with data provided in more or less any format. The use of a textual input language forever removes any future problems caused by binary format limitations. The ExtraData parser is based on the libConfuse configuration file parser library by Martin Hedenfalk, which is also used by GFS and EDF.

Each section in this document deals with one of the ExtraData constructs, as well as how to embed ExtraData in a WAD and how to associate it with a given map.

ExtraData will continue to be supported in future versions of Eternity, even though it will soon be superceded by support for the Universal Doom Map Format.

General Syntax

See EDF Syntax, as it is the same.

Embedding and Associating ExtraData

ExtraData is embedded directly as a text script into a lump of any name. This can be done with any number of wad file management tools, such as WinTex (though WinTex has some bugs which make the process more complicated), XWE or SLumpEd.

An ExtraData script is associated with a map via use of the MapInfo variable extradata. A map can only have one ExtraData script, but it is possible for multiple maps to share the same script.

Example of ExtraData specification via EMAPINFO:

  [MAP01]
  extradata = EDLUMP01

Mapthings

Mapthings define monsters, lamps, control points, items, etc -- anything that is spawned on the map at level start.

Each field in the mapthing definition, with the exception of the recordnum field, is optional. If a field is not provided, it takes on the default value indicated below the syntax information. Fields may also be provided in any order.

Note that the order of mapthing definitions in ExtraData is not important. The recordnum field serves to identify mapthing records.

Creating ExtraData Control Objects

Mapthing records in ExtraData are only associated with a special control object that must be placed on the map in the usual manner.

The ExtraData control object has a doomednum of 5004. Each control object specifies its corresponding ExtraData mapthing record number as an integer value in its mapthing options field. If your editor does not allow entering arbitrary values into the options field of mapthings, you will need to use the BOOM command-line editor, CLED. As of the initial writing time of this document, both DETH and Doom Builder support entering arbitrary integer values for the options field. Check your editor's documentation or user interface to verify if it supports this.

The x, y, and angle fields of the ExtraData control object are passed on to the thing which will be spawned at the control point's location, so those fields of the control object should be set normally. The true type and options fields of the thing to be spawned, along with any extended fields, are specified in the ExtraData record.

Any number of ExtraData control objects can reference the same ExtraData record. In the event that a control object references a non-existent ExtraData record, the ExtraData script for a level is missing, or the thing type referenced by an ExtraData record isn't valid, an Unknown thing will be spawned at the control point's location. Note that you cannot spawn ExtraData control objects using ExtraData. Attempting this will also result in an Unknown thing.

Mapthing Syntax and Fields

The syntax of the ExtraData mapthing record is as follows. Remember that all fields except the recordnum field are optional and can be specified in any order.

mapthing
{
  recordnum <unique number>
  
  // These fields are normal mapthing fields
  type      <doomednum> OR <EDF thingtype mnemonic>
  options   <options flag list>
  
  // These fields are ExtraData extensions
  tid       <number>
  args      { <special field>, ... }
  height    <number>
}

Explanation of fields:

recordnum

The recordnum serves to identify this record, and is the number which ExtraData control objects must use to associate themselves with a mapthing record. Every ExtraData mapthing record must have a unique record number. If a duplicate record number is detected, the engine will currently exit with an error message. The record number is limited to values between 0 and 65535 inclusive. Some editors may only allow input of numbers up to 32767 in the mapthing options field, or may treat values above 32767 as negative numbers. Beware of this.

type

Default: No meaningful default value; an Unknown thing will be spawned if not valid.

This field specifies the type of object to spawn at the location and angle of ExtraData control objects using this record. This field can accept one of two types of values. The first is a normal thingtype doomednum as specified via EDF and used by all editors. For example, the DOOM Imp's doomednum is 3001.

This field can also accept EDF thingtype mnemonics. EDF thingtype mnemonics must be prefixed with thing: -- this allows the parser to know it is dealing with a string instead of a number. EDF thingtypes must have a unique doomednum to be specified in an ExtraData mapthing record. If the specified EDF thingtype doesn't exist or has a doomednum of -1, an Unknown object will be spawned instead.

Example:

   mapthing { type 3001 }          // This record specifies an Imp via its doomednum
   
   mapthing { type DoomImp } // This record specifies an Imp by its EDF mnemonic
   

options

Default: No flags are set by default.

This field specifies the options (also known as mapthing flags). This field uses the same syntax as BEX/EDF flag strings, but the syntax will be reviewed here for completeness.

A BEX flag list is a string of flag names separated by whitespace, pipe characters, commas, or plus characters. In ExtraData, if a flag list contains whitespace, commas, or plus signs, it must be enclosed in double or single quotations. Flags are combined using bitwise-OR logic, so a flag name can be specified more than once. Specifying a flag name causes that flag to be turned on. The default state of all flags is off.

These are the flag values which are available for this field:

   Flag name   Decimal  Hex     Meaning
   ------------------------------------------------------------------------------
   EASY        1        0x0001  Thing appears in easy difficulties
   NORMAL      2        0x0002  Thing appears in "Hurt Me Plenty"
   HARD        4        0x0004  Thing appears in Ultra-Violence and Nightmare
   AMBUSH      8        0x0008  Thing is "deaf", will not wake up via sound
   NOTSINGLE   16       0x0010  Thing doesn't appear in single-player mode
   NOTDM       32       0x0020  Thing doesn't appear in deathmatch
   NOTCOOP     64       0x0040  Thing doesn't appear in cooperative multiplayer
   FRIEND      128      0x0080  Thing uses MBF friendly logic
   DORMANT     512      0x0200  Thing is dormant at map startup (script feature)
   ------------------------------------------------------------------------------
   

The mapthing options value 256 (0x0100) is reserved. If this bit is set, all BOOM, MBF, and Eternity extended mapthing bits will be cleared. This is to guard against editors like Hellmaker which set all bits they do not understand, instead of leaving them zero.

Example options fields -- All of these are equivalent:

   // This is the only syntax that does not require quotations.
   
   mapthing { options EASY|NORMAL|HARD }
   
   // All of these syntaxes must be quoted, because unquoted strings in 
   // ExtraData cannot contain spaces, commas, or plus signs.
   
   mapthing { options "EASY NORMAL HARD" }
   mapthing { options "EASY | NORMAL | HARD" }
   mapthing { options "EASY+NORMAL+HARD" }
   mapthing { options "EASY + NORMAL + HARD" }
   mapthing { options "EASY,NORMAL,HARD" }
   mapthing { options "EASY, NORMAL, HARD" }

tid

Default: 0

The TID, or "Thing ID", is a tag for mapthings which is used for identification in Small scripts. TID values must be positive numbers between 1 and 65535. The TID value zero means no TID. Negative TID values are reserved and are used to indicate special things within the engine. TIDs are not required to be unique, and most Small functions that accept TIDs will perform an action on all mapthings which bear the same TID. Things spawned within Small scripts can also be given TIDs.

args

Default: All args values default to zero.

The args field is a list of up to five special values which can have a broad range of meanings. Any values not provided in the args list will default, and if more than five values are provided, only the first five will be used. Currently, all args values are interpreted as integers (a non-number string evaluates to zero). This may change in the future.

Example args list:

   mapthing { args { 0, 1, 2, 3, 4 } }
   

height

Default: 0

For normal objects, this field indicates a distance above the floor that the thing will spawn at level start. For objects with the SPAWNCEILING flag, this field indicates a distance below the ceiling instead. This field will have no effect on objects which spawn at a randomized height.

Linedefs

Linedefs define walls, two-sided textures, and provide action triggers within maps.

Each field in the linedef definition, with the exception of the recordnum field, is optional. If a field is not provided, it takes on the default value indicated below the syntax information. Fields may also be provided in any order.

Note that the order of linedef definitions in ExtraData is not important. The recordnum field serves to identify linedef records.

Creating ExtraData Linedefs

Linedef records in ExtraData are associated only with lines which bear the ExtraData Control Line Special, #270. You can place this special into the normal "special" field of a line using virtually any map editor. Editors with Eternity-specific configurations should support this special natively.

Each control linedef specifies its corresponding ExtraData linedef record number as an integer value in its linedef tag field. If your editor does not allow entering arbitrary values up to 32767 into the tag field of linedefs, you will need to use the BOOM command-line editor, CLED. As of the initial writing time of this document, both DETH and Doom Builder support entering arbitrary integer values for the tag field. Check your editor's documentation or user interface to verify if it supports this.

The flags, sidedefs, textures, and location of the ExtraData control linedef are used normally by the line and cannot be altered from within ExtraData. The true special and tag fields of the linedef, along with any extended fields, are specified in the ExtraData record which the control linedef references.

Any number of ExtraData control linedefs can reference the same ExtraData record. In the event that a control linedef references a non-existent ExtraData record or the ExtraData script for a level is missing, the special and tag of the ExtraData control linedef will both be set to zero.

Linedef Syntax and Fields

The syntax of the ExtraData linedef record is as follows. Remember that all fields except the recordnum field are optional and can be specified in any order.

linedef
{
  recordnum <unique number>
  
  // These fields are normal linedef fields
  special <number> OR <special name>
  tag <number>
  
  // These fields are ExtraData extensions
  extflags <extended line flags list>
  args { <special field>, ... }
}

Explanation of fields:

recordnum

The recordnum serves to identify this record, and is the number which ExtraData control linedefs must use to associate themselves with a linedef record. Every ExtraData linedef record must have a unique record number. If a duplicate record number is detected, the engine will currently exit with an error message. The record number is limited to values between 0 and 32767 inclusive. Some editors may only allow input of numbers up to 255 in the linedef tag field. Beware of this.

special

Default: 0

The special field determines what type of action may be taken when a line is crossed, used, shot, etc. There are three types of linedef specials in Eternity: normal, generalized, and parameterized. Parameterized specials use the args field documented below to provide complete customization of line actions.

This field can accept numbers for any special type, including generalized and parameterized, but it can also accept special names for parameterized line types. See the Detailed parameterized linedef specification for a complete list of the available names.

tag

Default: 0

The tag of the linedef, used by DOOM-style line specials and sector effects.

extflags

Default: No flags are set by default.

This field specifies extended linedef flag values which impact the functionality of parameterized linedef specials. This field uses the same syntax as BEX/EDF flag strings, but the syntax will be reviewed here for completeness.

A BEX flag list is a string of flag names separated by whitespace, pipe characters, commas, or plus characters. In ExtraData, if a flag list contains whitespace, commas, or plus signs, it must be enclosed in double or single quotations. Flags are combined using bitwise-OR logic, so a flag name can be specified more than once. Specifying a flag name causes that flag to be turned on. The default state of all flags is off.

These are the flag values which are available for this field:

   Flag name   Decimal  Hex     Meaning
   ---------------------------------------------------------------------------------------
   CROSS       1        0x0001  Linedef can be activated by being crossed.
   USE         2        0x0002  Linedef can be activated by being used.
   IMPACT      4        0x0004  Linedef can be activated by being shot.
   PUSH        8        0x0008  Linedef can be activated by being pushed.
   PLAYER      16       0x0010  Linedef can be activated by players.
   MONSTER     32       0x0020  Linedef can be activated by objects with SPACMONSTER flag.
   MISSILE     64       0x0040  Linedef can be activated by objects with SPACMISSILE flag.
   REPEAT      128      0x0080  Linedef action is repeatable.
   1SONLY      256      0x0100  Linedef can only be activated from first side.
   ---------------------------------------------------------------------------------------
   

Notes: IMPACT is currently only implemented for bullet weapons. The ability to use IMPACT with MISSILE will be added in the near future. The PUSH style of activation is not implemented at all yet, so this flag currently does nothing.

Example flags fields -- All of these are equivalent:

   // This is the only syntax that does not require quotations.
   
   linedef { extflags CROSS|PLAYER|MISSILE|REPEAT }
   
   // All of these syntaxes must be quoted, because unquoted strings in 
   // ExtraData cannot contain spaces, commas, or plus signs.
   
   linedef { extflags "CROSS PLAYER MISSILE REPEAT" }
   linedef { extflags "CROSS | PLAYER | MISSILE | REPEAT" }
   linedef { extflags "CROSS+PLAYER+MISSILE+REPEAT" }
   linedef { extflags "CROSS + PLAYER + MISSILE + REPEAT" }
   linedef { extflags "CROSS,PLAYER,MISSILE,REPEAT" }
   linedef { extflags "CROSS, PLAYER, MISSILE, REPEAT" }

args

Default: All args values default to zero.

The args field is a list of up to five special values which can have a broad range of meanings. Any values not provided in the args list will default, and if more than five values are provided, only the first five will be used. Currently, all args values are interpreted as integers (a non-number string evaluates to zero). This may change in the future. The args list is used by parameterized linedef specials.

Example args list:

   linedef { args { 0, 1, 2, 3, 4 } }