Editing ExtraData
From Eternity Wiki
Jump to navigationJump to search
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
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. | |||
ExtraData | 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. | ||
Plans are in place to steadily introduce more features and functionality to ExtraData in future versions of the Eternity Engine. This documentation will be regularly updated to reflect all changes and additions. | |||
=General Syntax= | =General Syntax= | ||
''See [[EDF#Syntax|EDF Syntax]], as it is the same.'' | ''See [[EDF#Syntax|EDF Syntax]], as it is the same.'' | ||
Line 11: | Line 10: | ||
=Embedding and Associating ExtraData = | =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, | 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, including 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. | 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 | Example of ExtraData specification via MapInfo: | ||
[MAP01] | [MAP01] | ||
extradata = EDLUMP01 | extradata = EDLUMP01 | ||
ExtraData (as well as all other MapInfo variables) can be specified in either global or level-header MapInfo scripts. | |||
=Mapthings = | =Mapthings = | ||
Line 29: | Line 29: | ||
==Creating ExtraData Control Objects == | ==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. | Mapthing records in ExtraData are only associated with a special control object that must be placed on the map in the usual manner in your editor of choice. | ||
The ExtraData control object has a | 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. | 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 which the control thing references. | ||
Any number of ExtraData control objects can reference the same ExtraData record. In the event that a control object references a non- | Any number of ExtraData control objects can reference the same ExtraData record. In the event that a control object references a non-existant 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. See the [[EDF]] Documentation for information on the required Unknown thingtype definition. Note that you cannot spawn ExtraData control objects using ExtraData. Attempting this will also result in an Unknown thing. | ||
==Mapthing Syntax and Fields == | ==Mapthing Syntax and Fields == | ||
Line 42: | Line 42: | ||
mapthing | mapthing | ||
{ | { | ||
recordnum <unique number> | recordnum = <unique number> | ||
# These fields are normal mapthing fields | |||
type <doomednum> OR <EDF thingtype mnemonic> | type = <doomednum> OR <EDF thingtype mnemonic> | ||
options <options flag list> | options = <options flag list> | ||
# These fields are ExtraData extensions | |||
tid | tid = <number> | ||
args = { <special field>, ... } | |||
args { <special field>, ... } | height = <number> | ||
height <number> | |||
} | } | ||
===Explanation of fields:=== | ===Explanation of fields:=== | ||
Line 59: | Line 58: | ||
====type==== | ====type==== | ||
Default: No meaningful default value | Default: No meaningful default value, an Unknown thing will be spawned. | ||
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 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. | 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: | Example: | ||
mapthing { type 3001 } // This record specifies an Imp via its doomednum | mapthing { type = 3001 } // This record specifies an Imp via its doomednum | ||
mapthing { type = thing:DoomImp } // This record specifies an Imp by its EDF mnemonic | |||
====options==== | ====options==== | ||
Default: No flags are set by default. | Default: No flags are set by default. | ||
Line 80: | Line 77: | ||
These are the flag values which are available for this field: | These are the flag values which are available for this field: | ||
Flag name Meaning | Flag name Decimal Hex Meaning | ||
------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ||
EASY Thing appears in easy difficulties | EASY 1 0x0001 Thing appears in easy difficulties | ||
NORMAL Thing appears in "Hurt Me Plenty" | NORMAL 2 0x0002 Thing appears in "Hurt Me Plenty" | ||
HARD Thing appears in Ultra-Violence and Nightmare | HARD 4 0x0004 Thing appears in Ultra-Violence and Nightmare | ||
AMBUSH Thing is "deaf", will not wake up via sound | AMBUSH 8 0x0008 Thing is "deaf", will not wake up via sound | ||
NOTSINGLE Thing doesn't appear in single-player mode | NOTSINGLE 16 0x0010 Thing doesn't appear in single-player mode | ||
NOTDM Thing doesn't appear in deathmatch | NOTDM 32 0x0020 Thing doesn't appear in deathmatch | ||
NOTCOOP Thing doesn't appear in cooperative multiplayer | NOTCOOP 64 0x0040 Thing doesn't appear in cooperative multiplayer | ||
FRIEND Thing uses MBF friendly logic | FRIEND 128 0x0080 Thing uses MBF friendly logic | ||
DORMANT Thing is dormant at map startup (script feature) | DORMANT 512 0x0200 Thing is dormant at map startup (script feature) | ||
------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ||
Line 97: | Line 93: | ||
Example options fields -- All of these are equivalent: | Example options fields -- All of these are equivalent: | ||
# This is the only syntax that does not require quotations. | |||
mapthing { options EASY|NORMAL|HARD } | 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" } | ||
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==== | ====tid==== | ||
Default: 0 | Default: 0 | ||
The TID, or "Thing ID", is a tag for mapthings which is used for identification in [[ | 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==== | ====args==== | ||
Line 127: | Line 117: | ||
Example args list: | Example args list: | ||
mapthing { args { 0, 1, 2, 3, 4 } } | mapthing { args = { 0, 1, 2, 3, 4 } } | ||
====height==== | ====height==== | ||
Default: 0 | 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. | 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 = | ||
Line 144: | Line 134: | ||
==Creating ExtraData Linedefs == | ==Creating ExtraData Linedefs == | ||
Linedef records in ExtraData are associated | 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 | 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 | 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 linedefs can reference the same ExtraData record. In the event that a control linedef references a non- | Any number of ExtraData control linedefs can reference the same ExtraData record. In the event that a control linedef references a non-existant 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 == | ==Linedef Syntax and Fields == | ||
Line 157: | Line 147: | ||
linedef | linedef | ||
{ | { | ||
recordnum <unique number> | recordnum = <unique number> | ||
# These fields are normal linedef fields | |||
special <number> OR <special name> | special = <number> OR <special name> OR <generalized specifier> | ||
tag <number> | tag = <number> | ||
# These fields are ExtraData extensions | |||
extflags <extended line flags list> | extflags = <extended line flags list> | ||
args { <special field>, ... } | args = { <special field>, ... } | ||
} | } | ||
===Explanation of fields: === | ===Explanation of fields: === | ||
Line 178: | Line 166: | ||
The special field determines what [[Linedef_types|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. | The special field determines what [[Linedef_types|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 | This field can accept numbers for any special type, including generalized and parameterized, but it can also accept special names for all line types. See the [[Detailed parameterized linedef specification]] for a complete list of the names available and an explanation of how to specify generalized specials. | ||
====tag==== | ====tag==== | ||
Default: 0 | |||
The tag of the linedef, used by DOOM-style line specials and sector effects. | The tag of the linedef, used by DOOM-style line specials and sector effects. | ||
====extflags==== | ====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. | 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. | ||
Line 193: | Line 181: | ||
These are the flag values which are available for this field: | These are the flag values which are available for this field: | ||
Flag name Meaning | Flag name Decimal Hex Meaning | ||
--------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ||
CROSS | CROSS 1 0x0001 Linedef can be activated by being crossed. | ||
USE | USE 2 0x0002 Linedef can be activated by being used. | ||
IMPACT Linedef can be activated by being shot. | IMPACT 4 0x0004 Linedef can be activated by being shot. | ||
PUSH | PUSH 8 0x0008 Linedef can be activated by being pushed. | ||
PLAYER | PLAYER 16 0x0010 Linedef can be activated by players. | ||
MONSTER Linedef can be activated by objects with SPACMONSTER flag. | MONSTER 32 0x0020 Linedef can be activated by objects with SPACMONSTER flag. | ||
MISSILE Linedef can be activated by objects with SPACMISSILE flag. | MISSILE 64 0x0040 Linedef can be activated by objects with SPACMISSILE flag. | ||
REPEAT 128 0x0080 Linedef action is repeatable. | |||
REPEAT | 1SONLY 256 0x0100 Linedef can only be activated from first side. | ||
1SONLY | |||
--------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ||
Notes: IMPACT is currently only implemented for bullet weapons. | 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: | Example flags fields -- All of these are equivalent: | ||
# This is the only syntax that does not require quotations. | |||
linedef { extflags CROSS|PLAYER|MISSILE|REPEAT } | 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" } | ||
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==== | ====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. | 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: | Example args list: | ||
linedef { args { 0, 1, 2, 3, 4 } } | linedef { args = { 0, 1, 2, 3, 4 } } | ||