Editing ExtraData

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|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 SLumpEd, SLADE 3, or XWE. 

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   Meaning
    ------------------------------------------------------------------------------
    EASY        Thing appears in easy difficulties
    NORMAL      Thing appears in "Hurt Me Plenty"
    HARD        Thing appears in Ultra-Violence and Nightmare
    AMBUSH      Thing is "deaf", will not wake up via sound
    NOTSINGLE   Thing doesn't appear in single-player mode
    NOTDM       Thing doesn't appear in deathmatch
    NOTCOOP     Thing doesn't appear in cooperative multiplayer
    FRIEND      Thing uses MBF friendly logic
    DORMANT     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.

Glad I've finally found smoething I agree with!

=Sectors=

Sectors define distinct areas of the map that are bordered by linedefs, with floor and ceiling properties, lighting data, and specials. 

Each field in the sector 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 sector definitions in ExtraData is not important. The '''recordnum''' field serves to identify sector records. 

==Creating ExtraData Sectors==

Sector records in ExtraData are associated with lines which bear the ExtraData Sector Control Special (401). The linedef's front side sector is the map sector that will receive properties from the ExtraData record which is specified by number in the linedef's tag.

Since ExtraData is attached to sectors via linedefs and not through overriding any of the sectors' native fields, you specify all of the normal data for a sector in the map itself, and overriding that data through ExtraData sector records is not supported.

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

==Sector Syntax and Fields ==

The syntax of the ExtraData sector record is as follows. Remember that all fields except the '''recordnum''' field are optional and can be specified in any order. 
 sector
 {
   recordnum <unique number>
   
   // These fields are ExtraData extensions to sector data
   flags <sector flag list>
   flags.add <sector flag list>
   flags.remove <sector flag list>
   damage <integer>
   damagemask <integer>
   damagemod <method of damage type>
   damageflags <sector damage flags list>
   damageflags.add <sector damage flags list>
   damageflags.remove <sector damage flags list>
   floorterrain <terrain name>
   floorangle <float>  
   flooroffsetx <float>
   flooroffsety <float>
   ceilingterrain <terrain name>
   ceilingangle <float>
   ceilingoffsetx <float>
   ceilingoffsety <float>
   colormaptop <lump name>
   colormapmid <lump name>
   colormapbottom <lump name>
   portalflags.floor <portal flags list>
   portalflags.ceiling <portal flags list>
   overlayalpha.floor <percentage or value from 0 to 255>
   overlayalpha.ceiling <percentage or value from 0 to 255>
 }
===Explanation of fields: ===
====recordnum====
The recordnum serves to identify this record, and is the number which ExtraData sector control linedefs must use to associate themselves with a sector record. Every ExtraData sector 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. 

====flags====
:''Default: No flags are set by default. ''

This field specifies sector flag values which specify various properties of sectors. This field uses the same syntax as BEX/EDF flag strings. 

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

    Flag name     Meaning
    ---------------------------------------------------------------------------------------
    SECRET        Sector is secret
    FRICTION      Sector has friction enabled, if targeted by a BOOM friction transfer line
    PUSH          Sector has BOOM push effects enabled
    KILLSOUND     Objects in sector cannot make sounds.
    KILLMOVESOUND Sector makes no movement sounds, even if it has a special sound sequence
    ---------------------------------------------------------------------------------------
    
Example flags fields -- All of these are equivalent: 
    // This is the only syntax that does not require quotations.
    
    sector { flags SECRET|FRICTION|KILLMOVESOUND }
    
    // All of these syntaxes must be quoted, because unquoted strings in 
    // ExtraData cannot contain spaces, commas, or plus signs.
    
    sector { flags "SECRET FRICTION KILLMOVESOUND" }
    sector { flags "SECRET | FRICTION | KILLMOVESOUND" }
    sector { flags "SECRET+FRICTION+KILLMOVESOUND" }
    sector { flags "SECRET + FRICTION + KILLMOVESOUND" }
    sector { flags "SECRET,FRICTION,KILLMOVESOUND" }
    sector { flags "SECRET, FRICTION, KILLMOVESOUND" }

====flags.add====
:''Default: No flags are set by default. ''

This is a list of sector flags to add to the sector. This is supported because some sector specials (such as sector special 9, "Secret") imply that certain sector flags will be set on the sector before ExtraData is applied. If you wish to only add flags and not override any that may have been set by sector specials, use this field to specify only the flags that you wish to be added to the sector.

====flags.remove====
:''Default: No flags are set by default. ''

This is a list of sector flags to remove from the sector. If you wish to only remove flags and not override any that may have been set by sector specials, use this field to specify only the flags that you wish to be removed from the sector.

====damage====
:''Default: 0''

Specifies the amount of damage this sector does to players if the players are standing inside the sector and do not meet any special exemption criteria, such as wearing a Radiation Suit. This amount is done at each damage opportunity, which is determined by the '''damagemask''' field.

====damagemask====
:''Default: 0''

Specifies the interval in gametics between damage opportunities for a player standing in this sector. The default value of 0 will cause the sector to do constant and instantaneous damage every gametic. Setting this value to an integer greater than 0 will cause damage to be done every Nth gametic, with N being the value of this field. The default DOOM nukage types all use a damagemask of 32, which is roughly once per in-game second (there are 35 gametics per second).

====damagemod====
:''Default: "Unknown"''

Specifies the type of damage done by this sector. If "Unknown" is specified, the damage done is generic. The value specified should be a valid EDF damagetype mnemonic. If it is not, "Unknown" will be used. This can be used to have a sector type trigger special pain and death states when it deals damage. For example, you can use '''slime''' or '''lava''' damagemod.

====damageflags====
:''Default: No flags are set by default.''

This field specifies sector damage flag values which affect the manner in which a sector does damage. This field uses the same syntax as BEX/EDF flag strings. 

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

    Flag name     Meaning
    ---------------------------------------------------------------------------------------
    LEAKYSUIT     The player may take damage at random even if he has the radsuit powerup
    IGNORESUIT    Radiation suit powerups are ignored entirely
    ENDGODMODE    God mode will be disabled when the player enters this sector
    EXITLEVEL     The player will exit if has < 11 health and this sector tries to do damage
    TERRAINHIT    A TerrainTypes hit will occur when this sector does damage
    ---------------------------------------------------------------------------------------

====damageflags.add====
:''Default: No flags are set by default.''

Because some sector types imply the activation of various sector damageflags (for example, DOOM sector type 11 sets sector damageflags ENDGODMODE and EXITLEVEL), this field is supported to add additional damageflags to any that may have been set by the  map itself. Simply specify whatever flags you wish to have added to those that are already set.

====damageflags.remove====
:''Default: No flags are set by default.''

As with damageflags.add, it may be desirable to turn off some flags that were set by sector specials or other portions of the map data. Use this field to specify any sector damage flags you want to remove from sectors.

====floorterrain====
:''Default: "@flat"''

Specifies an EDF TerrainTypes mnemonic for the type of terrain this sector should exhibit on its floor. If left to default or specified with an invalid name, the terrain of the sector will be determined by its floorpic as usual.

====floorangle====
:''Default: 0 (East, or upper edge to the north)''

Specifies the angle of the floor flat in floating-point degrees from 0 to 359. Note that for compatibility with ZDoom, the angle specified advances in a '''clockwise''' fashion, contrary to most other angles in the DOOM engine.

====flooroffsetx/flooroffsety====
:''Default: 0''

Specifies the x and y offsets of the floor flat, relative to the normal floor grid, in floating point units.

====ceilingterrain====
:''Default: "@flat"''

Specifies an EDF TerrainTypes mnemonic for the type of terrain this sector should exhibit on its ceiling. If left to default or specified with an invalid name, the terrain of the sector will be determined by its floorpic as usual. This currently only affects the behavior of bullet puffs when particles are enabled.

====ceilingangle====
:''Default: 0 (East, or upper edge to the north)''

Specifies the angle of the ceiling flat in floating-point degrees from 0 to 359. Note that for compatibility with ZDoom, the angle specified advances in a '''clockwise''' fashion, contrary to most other angles in the DOOM engine.

====flooroffsetx/flooroffsety====
:''Default: 0''

Specifies the x and y offsets of the ceiling flat, relative to the normal ceiling grid, in floating point units.

====colormaptop====
:''Default: "@default"''

Specifies the colormap lump to use when a player's viewpoint is above the fake ceiling of a BOOM 242 "deep water" effect applying to this sector. If left to default, the global colormap from MapInfo will be used as normal, unless one is specified by the 242 effect.

====colormapmid====
:''Default: "@default"''

Specifies the colormap lump to use when a player's viewpoint is between the normal floor and ceiling for an ordinary sector, or between the fake floor and ceiling for a BOOM 242 "deep water" sector. If left to default, the global colormap from MapInfo will be used as normal, unless one is specified by a 242 effect.

====colormapbottom====
:''Default: "@default"''

Specifies the colormap lump to use when a player's viewpoint is below the fake floor of a BOOM 242 "deep water" effect applying to this sector. If left to default, the global colormap from MapInfo will be used as normal, unless one is specified by the 242 effect.

====portalflags====
:''Default: No flags are set by default.''

These two fields (portalflags.floor and portalflags.ceiling) specify portal property flag values which affect the rendering and behavior of portals attached to this sector's surfaces. These fields use the same syntax as BEX/EDF flag strings. 

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

    Flag name     Meaning
    ---------------------------------------------------------------------------------------
    DISABLED      Portal is completely disabled
    NORENDER      Portal will not be rendered, but may still be interactive
    NOPASS        Objects cannot pass through the portal even if it is a linked portal
    BLOCKSOUND    Sound will not traverse through a linked portal
    OVERLAY       The portal will render the sector's flat as a blended overlay
    ADDITIVE      If OVERLAY is also specified, the overlay will use additive blending
    USEGLOBALTEX  Reserved for future per-portal texture specification
    ---------------------------------------------------------------------------------------

====overlayalpha====
:''Default'': 100%

These two fields (overlayalpha.floor and overlayalpha.ceiling) specify the opacity of the corresponding portal overlay, if any exists. You can specify either a percentage value from 0% to 100%, or a plain integer number from 0 to 255. 100%/255 are completely solid, while 0% is invisible.