EDF thing reference

From Eternity Wiki
Revision as of 18:22, 8 February 2010 by Printz (talk | contribs) (States)
Jump to: navigation, search

Thing types define monsters, lamps, control points, items, etc -- anything that moves, occupies space, can display a sprite, or is useful for singling out locations. Things have unique names, or mnemonics, for easy identification. They're referenced in several places by their name, such as the console command Summon, or action functions dealing with spawning things (such as Spawn or MissileAttack).

If a thing type's mnemonic is not unique, the latest definition of a thing type with that mnemonic replaces any earlier ones. Like most other identifiers in EDF (but not lump names or subnames), thing type mnemonics are completely case-insensitive.

New objects, created via EDF files or wad lumps, can be later tweaked with Dehacked (BEX) patches, if they're given a unique dehackednum entry. For forward compatibility, the dehackednum has to be greater than or equal to 10000.

For placing the thing on the map, an integer field called doomednum must be specified. For forward compatibility it has to be greater than or equal to 20000 or in the 3000-3999 range. Due to how binary WAD files format their THINGS lumps, doomednum values have to be less than 32767, though textmode representations such as ExtraData or UDMF solve this limit.


thingtype <unique name>
  doomednum              <number>
  dehackednum            <unique number>
  inherits               <thingtype>
  basictype              <basic type qualifier>
  spawnstate             <frame>
  seestate               <frame>
  painstate              <frame>
  dmg_painstates         {<damage type>, <frame>, ...}
  dmg_painstates.add     {<damage type>, <frame>, ...}
  dmg_painstates.remove  {<damage type>, ...}
  meleestate             <frame>
  missilestate           <frame>
  deathstate             <frame>
  dmg_deathstates        {<damage type>, <frame>, ...}
  dmg_deathstates.add    {<damage type>, <frame>, ...}
  dmg_deathstates.remove {<damage type>, ...}
  xdeathstate            <frame>
  raisestate             <frame>
  crashstate             <frame>

  seesound               <sound>
  attacksound            <sound>
  painsound              <sound>
  deathsound             <sound>
  activesound            <sound>

  spawnhealth            <number>
  reactiontime           <number>
  painchance             <number>
  speed                  <number OR floating-point number>
  fastspeed              <number OR floating-point number>
  radius                 <floating-point number>
  height                 <floating-point number>
  correct_height         <floating-point number>
  mass                   <number>
  respawntime            <number>
  respawnchance          <number>

  damage                 <number>
  dmgspecial             <dmgspecial name>

  damagefactor           <damage type>, <floating point number>
  damagefactor           <damage type>, <floating point number>

  topdamage              <number>
  topdamagemask          <number>
  mod                    <MOD name OR number>
  obituary_normal        <string>
  obituary_melee         <string>

  bloodcolor             <number>
  nukespecial            <BEX codepointer mnemonic>
  droptype               <thing type mnemonic>

  cflags                 <flag list>
  addflags               <flag list>
  remflags               <flag list>
  flags                  <flag list>
  flags2                 <flag list>
  flags3                 <flag list>
  flags4                 <flag list>
  particlefx             <particle effect flag list>

  translucency           <number OR percentage>
  translation            <number OR translation table lump name>
  skinsprite             <sprite>
  defaultsprite          <sprite>
  alphavelocity          <floating-point number>
  xscale                 <floating-point number>
  yscale                 <floating-point number>

  acs_spawndata          {num <number> modes <mnemonic>}

Explanation of fields

ID / Type Info

  • doomednum
Default = -1
The identification number, which makes this actor type placeable in maps. Zombieman monsters for example have doomednum 3004. Objects which don't need to be placed on the map can have doomednum -1. For EDF, recommended numbers are in the ranges 3000-3999 and 20000 up. Other numbers may be used by future versions of Eternity, so they're not safe to use.
  • dehackednum
Default = -1
Fake array index number, for Dehacked patch (BEX or DEH file) compatibility. It has to be an unique number if not -1. Safe numbers are from 10000 up.
  • inherits
Default = (nothing)
Sets the thing type from which this will copy properties. All of the properties except dehackednum will be copied from the base actor type.
  • basictype
Default = (nothing)
Basictype is a list of common flags used in Doom and derived games. Using basictype instead of setting individual flags is encouraged, in order to keep up with Eternity engine updates. Other flags may be subsequently added or removed with addflags or remflags. The basictype mnemonics follow:
  • Monster
An ordinary walking monster with no fancy features.
  • FlyingMonster
An ordinary flying monster.
  • FriendlyHelper
A player helper with maximum friendliness options.
  • Projectile
A standard projectile.
  • PlayerProjectile
A projectile for use by players.
  • Seeker
A missile prepared to be fired by homing missile codepointers.
  • SolidDecor
A solid decorative item.
cflags SOLID
  • HangingDecor
A hanging decorative item that is passable even without 3D object clipping.
  • SolidHangingDecor
A solid hanging decorative item.
  • ShootableDecor
A shootable decorative item.
  • Fog
A fog item such as telefog or item fog.
  • Item
A collectable item. Doesn't count towards the item score.
cflags SPECIAL
  • ItemCount
A collectable item. Counts for item score.
  • TerrainBase
A TerrainTypes base item.
  • TerrainChunk
A TerrainTypes chunk item.
  • ControlPoint
An inert control point.
spawnstate S_TNT1
  • ControlPointGrav
An control point that is subject to gravity. Because of this, it's not considered inert.
spawnstate S_TNT1


  • spawnstate
Default = S_NULL
Sets the frame which a thing starts in when it is spawned. Monsters generally use this frame to stand still and look for targets. If the object is supposed to have any dynamic purpose or be visible, do not leave the spawnstate at S_NULL.
  • seestate
Default = S_NULL
Sets the frame which a monster will jump to when it sees or hears a target during a Look (monster standing unawakened) check.
  • painstate
Default = S_NULL
Sets the frame a thing may randomly enter when it has been injured. If set to S_NULL, the creature will be removed instantly from the game if the random check succeeds.
  • dmg_painstates
Default = (nothing)
This is a list of one or more damagetype/frame pairs, enclosed in braces. For example:
   Fire, S_HPLAY_FPAIN1,

makes the actor go to frame S_HPLAY_FPAIN1 when damaged by fire, or to S_HPLAY_LPAIN1 when harmed by lava. It defaults to its painstate if the damage is of another nature. For now, damage types are hard coded, even though they can be defined by EDF, so the number of possible damage types is limited.

  • dmg_painstates.add
  • dmg_painstates.remove
Can be used for derived actor types, who can have more or fewer specialized pain states than their ancestors. Dmg_painstates.add has the same format as dmg_painstates, but dmg_painstates.remove only lists the damagetypes. For example:
   Fire, lava

makes them die normally from fire or lava, without going to special pain states.

  • meleestate
Default = S_NULL
If this frame is not S_NULL, monsters will have a slightly lower range attack probability and when they are within about 64 units of their target, they will enter this frame to perform a melee attack.
  • missilestate
Default = S_NULL
If this frame is not S_NULL, monsters chasing a target will randomly enter it to perform a missile attack.
  • deathstate
Default = S_NULL
When a thing dies normally, it will enter this state. If the state is S_NULL, the thing will disappear forever.
  • dmg_deathstates
  • dmg_deathstates.add
  • dmg_deathstates.remove
Defaults = (nothing)
These three properties work similar to dmg_painstates*, in that they allow the object to enter special frames depending on the damage type suffered. The formats are the same.
  • xdeathstate
Default = S_NULL
If a thing dies by taking enough damage that its health is equal to its negated spawnhealth value (or negated 0.5 spawnhealth value in Heretic), it will enter this frame instead of its deathstate. If this frame is S_NULL, the thing will always die normally.
  • raisestate
Default = S_NULL
If this frame is not S_NULL, a creature running VileChase codepointers can perform a resurrection on this actor. When this occurs, the actor will enter this frame along with being restored.
  • crashstate
Default = S_NULL
When a thing with this state dies and then subsequently hits the ground, it will enter this state. If this state S_NULL, it is not used.


  • seesound
Default = none
Sets the sound that a monster will play when it awakens. This sound is also played by missiles when they are shot. (Note: "none" is a special mnemonic for no sound)
  • attacksound
Default = none
Sets a sound used by some monster attacks, including the Lost Soul's charge, or melee attacks.
  • painsound
Default = none
Sets the sound played by the Pain codepointer when this thing uses it.
  • deathsound
Default = none
Sound played by the Scream codepointer. Used to play monster death sounds.
  • activesound
Default = none
Sets the sound used by a thing when it is wandering around. A thing is given a 3 out of 256 chance (1.17%) of making this sound every time it calls the Chase codepointer. There are some new flags3 flags which can alter the behavior of this sound.

Basic Stats

  • spawnhealth
Default = 1000
Sets a thing's maximum amount of life.
  • reactiontime
Default = 8
Sets an amount of time that a thing must wait under certain circumstances. Monsters use this value as a means to control their rate of attack. This value is also used as an internal field for varying purposes, but those uses are not editable.
  • painchance
Default = 0
Sets the chance out of 255 that this thing will enter its painstate when it is injured. A thing with 0 painchance will never feel pain, whereas a thing with 255 painchance will always feel pain. If a thing has a painchance greater than zero, it should have a valid painstate, otherwise it will disappear forever.
  • speed
Default = 0
Value used by monsters as a movement delta per walking frame. The monster will move by an amount relative to this value each time it uses the Chase codepointer. For missiles, this value is a fixed-point number (multiplied by 65536), and represents a constant speed by which the missile advances every game tic. Missile speed is not affected by the missile frame durations, whereas monster walking speed is.
This field also supports floating-point values. When a floating-point value is provided, it will be translated into the corresponding fixed-point value. This means that a value of 10.0 is equivalent to the integer value 655360 (10*65536). It is NOT equivalent to 10. This distinction is very important. Small integer speed values are appropriate for monsters, whereas floating-point values will be suitable only for missiles.
  • fastspeed
Default = 0
When the game is switched into Nightmare difficulty or -fast mode is active, all thing types with a non-zero fastspeed will have their speed fields changed to their fastspeed value. This enables editing of the -fast speed of projectiles and monsters. For detailed information on speed, see the speed field itself above. Note: as of EDF 1.2, this field also supports floating-point numbers, with the same meaning as that for the speed field.
  • radius
Default = 20.0
Floating-point value that represents the radius of this thing type. A thing can fit into corridors which are at least as wide as this value times two, plus one unit (ie a thing with radius 32 can fit into a 65-wide hallway). The maximum value this field *should* have is 64.0 units. However, the game breaks its own rule here, giving several monsters radii up to 128 units. These monsters, which include the Mancubus, Arachnotron, and Spider Demon, exhibit clipping errors which enable other things to walk into them, and which can cause some moving sectors to malfunction. Avoid giving things radii larger than 64.0 to remain absolutely safe.
  • height
Default = 16.0
Floating-point value that represents the height of this thing type. A thing can fit into areas which are of this exact height or taller. Note that in DOOM, this value is only used to see where a monster can fit relative to walls and floor/ceiling heights. For purposes of clipping against other things, monsters were considered to be infinitely tall. However, Eternity's extended 3D object clipping enables this field to also be used to allow or disallow things to pass over, under, or stand on this thing.
  • correct_height
Default = 0.0
Floating-point value that represents a height for this thing type which is corrected for 3D object clipping. When 3D object clipping is enabled and the comp_theights variable is set to off, objects which have a non-zero correct_height field will begin to use this value for their height instead of the normal height field. If an object has the 3DDECORATION flags3 bit set, it will still clip missiles at its original height instead of at this value, so that playability of old maps is not altered. This field will generally only be necessary for old DOOM objects, which have now been assigned correct_height values in the default things.edf module. Use for new objects is discouraged; instead, set the height field above to the proper value.
  • mass
Default = 100
Normal integer value that serves as a mass factor for this object. Mass affects the amount of thrust an object is given when it is damaged, the amount of effect an archvile's attack can have on it, and for bouncing objects, the rate at which they fall. Objects with a mass less than 10 will cause small terrain hits when landing on terrain that supports small splashes.
  • respawntime
Default = 420
Sets the number of gametics before the monster may respawn. A tic is 1/35 of a second.
  • respawnchance
Default = 4
Sets the chance out of 255 that the monster may respawn after respawntime has passed. The check is done for each tic that the monster isn't blocked.

Damage Properties

  • damage
Default = 0
This number is used as a damage multiplier when a missile hits a thing. The damage formula used is:
      damage = ((rnd % 8) + 1) * missiledamage   
This field is also used as a parameter by some new, parameterized codepointers, including BetaSkullAttack and Detonate.
  • dmgspecial
Default = "none"
The dmgspecial field allows specification of a special action that will be taken when this object is involved in damaging another object as the inflictor (an inflictor is the object actually doing the damage, and not necessarily the object that is blamed for the damage). Supported values and their meanings are as follows:
  • none
This is the default value. No special action is taken; the object is normal when damaging other things.
  • MinotaurCharge
If the thing is flying like a skull (has flags bit SKULLFLY set), it will inflict a large amount of thrust on the target along the vector of the impact, will hit it directly for ((rnd % 8) + 1) * 6 damage, and if the target is a player, the player's controls will be frozen for 14 + (rnd % 8) gametics. When the thing is not in SKULLFLY mode, normal damage is done by all attacks.
  • Whirlwind
The target will have its angle and x/y momenta modified by random amounts. If the current level time has the 5th bit (value 16) set and the target is not a boss (possesses the BOSS flag), the target will be given randomized z momentum up to but no greater than 12 units per tic. When the level time is divisible by 8, the target will be hit directly for 3 damage.
  • DamageFactor
This sets up the monster's resistance to various damage types. 0 means invincible, 1 full damage. This property has a distinct syntax: there may be as many DamageFactor lines as damage resistances. Example:
damagefactor fire, 0.3
damagefactor lava, 0.2

As seen above, no braces are used, and the arguments are separated by commas.

  • topdamage
Default = 0
This number is a constant amount of damage inflicted on any shootable object that stands on top of this object when 3D object clipping is active. This is useful for objects such as torches and flaming barrels. The frequency of damage is determined by the topdamagemask field.
  • topdamagemask
Default = 0
This number determines how often a thing with a non-zero topdamage field burns objects that are standing on top of it. This number should be a power of two minus 1 to work properly, such as 1, 3, 7, 15, or 31 (31 would be approximately once per second and is used by DOOM's nukage sector types). New to EDF 1.7.
  • mod
Default = UNKNOWN (0)
Special Means of Death flag for this thing type. Currently supported values follow below. The use of numbers in this field is now considered deprecated. Please use the descriptive textual MOD names in all new EDF projects.
   Mod Name    Number
   UNKNOWN       0
   FIST          1
   PISTOL        2
   SHOTGUN       3
   CHAINGUN      4
   ROCKET        5
   R_SPLASH      6
   PLASMA        7
   BFG           8
   BFG_SPLASH    9
   CHAINSAW      10
   SSHOTGUN      11
   SLIME         12
   LAVA          13
   CRUSH         14
   TELEFRAG      15
   FALLING       16
   SUICIDE       17
   BARREL        18
   SPLASH        19
   HIT           20
   BETABFG       22
   BFGBURST      23
   GRENADE       25
  • obituary_normal
Default = empty
Defines the obituary seen by players when killed by a projectile or other miscellaneous attack by a monster. If the obituary is not defined for this type, it will simply read that the player died. Note that you are only allowed to specify an obituary starting immediately after the player's name. If you want an obituary to say "Player was flamed", then simply make the obituary read "was flamed".
  • obituary_melee
Default = empty
Defines the obituary seen by players when killed by a monster's melee attack. If the obituary is not defined for this type, it will simply read that the player died. Note that you are only allowed to specify an obituary starting immediately after the player's name. If you want an obituary to say "Player was stabbed mercilessly", then simply make the obituary read "was stabbed mercilessly".
Specifying this field is not necessary for most thing types. It IS highly useful for controlling the obituaries triggered by player projectiles, however. Some of the values above are not fully supported yet. Eventually the LAVA type will cause fire death animations for things which define them.

Pain/Death Properties

  • bloodcolor
Default = 0
Allows this thing type to have differently colored blood when particle blood effects are enabled (this does not currently have any effect on blood sprites). Currently available blood color values are as follows:
    Blood color       Number
    Red (normal)        0
    Grey                1
    Green               2
    Blue                3
    Yellow              4
    Black               5
    Purple              6
    White               7
    Orange              8

  • nukespecial
Default = NULL
This field is the name of a special codepointer to call when the player uses the KILLEM cheat to kill all monsters. Currently only two special pointers are provided for this purpose, PainNukeSpec and SorcNukeSpec. These enable monsters with spawn-on-death actions to either spawn enemies early, or not at all. See the Eternity Engine Definitive Codepointer Reference for detailed information.
  • droptype
Default = NONE
This field allows the type of thing that is dropped by this thing when it dies to be edited. This field should either be a valid thing type mnemonic, or the special value NONE.


  • cflags
Default = ""
This field allows specification of all the thing's flag values in one single flag list. When this field is defined, flags, flags2, flags3 and flags4 are ignored. The only caveat to this field is that the flags bit "SLIDE", which has no effect, cannot be specified in this field. If SLIDE is used, it will activate the flags3 bit with the same name, which has the expected effect. All other flags will be assigned to their appropriate internal fields as normal. See the Thing type flags for their descriptions.
  • addflags
Default = ""
This field specifies a combined list of flags to be added to the thing's existing flags values (this works the same as the cflags field above). Flags in this list are "turned on" in the thing. If flags are listed here which are already "on," there is no effect on those flags. This field is most useful within thingdelta sections and in concert with thing type inheritance.
  • remflags
Default = ""
This field specifies a combined list of flags to be subtracted from the thing's existing flags values (this works the same as the cflags field above). Flags in this list are "turned off" in the thing, as if they had never been listed. If flags are listed here which are not already "on," there is no effect on those flags. This field is most useful within thingdelta sections and in concert with thing type inheritance. This field will be applied AFTER the addflags field is applied, so it could potentially turn off flags turned on by that field.
  • flags
Default = ""
This field controls a number of thing type properties using bit flags, where each bit in the field stands for some effect, and has the value of being either on or off. See the Thing type flags List, for the values which can be used in this field. Remember that if whitespace or disallowed characters are used, this field's value must be enclosed in quotation marks.
  • flags2
Default = ""
Similar to flags but takes a different set of values with different meanings. See the Thing type flags List, for the values which can be used in this field. Remember that if whitespace or disallowed characters are used, this field's value must be enclosed in quotation marks.
  • flags3
Default = ""
Similar to flags, but takes a different set of values with different meanings. See the Thing type flags List, for the values which can be used in this field. Remember that if whitespace or disallowed characters are used, this field's value must be enclosed in quotation marks.
  • flags4
Default = ""
Similar to flags, but takes a different set of values with different meanings. See the Thing type flags List, for the values which can be used in this field. Remember that if whitespace or disallowed characters are used, this field's value must be enclosed in quotation marks.
  • particlefx
Default = 0
This field is a flag field with syntax identical to the flags, flags2, and flags3 fields, but which accepts the following values which control what persistent particle effects are associated with objects of this type:
    Flag name       Hex Value     Effect
    ROCKET          0x00000001    Rocket trail
    GRENADE         0x00000002    Grenade trail
    FLIES           0x00000004    Swarm of flies w/ sound
    BFG             0x00000008    BFG particle swarm
    FLIESONDEATH    0x00000010    Flies when object dies
    DRIP            0x00000020    Parameterized drip effect
    REDFOUNTAIN     0x00010000    Red fountain
    GREENFOUNTAIN   0x00020000    Green fountain
    BLUEFOUNTAIN    0x00030000    Blue fountain
    YELLOWFOUNTAIN  0x00040000    Yellow fountain
    PURPLEFOUNTAIN  0x00050000    Purple fountain
    BLACKFOUNTAIN   0x00060000    Black fountain
    WHITEFOUNTAIN   0x00070000    White fountain
Note that the fountain flag values cannot be combined with each other. Doing so will simply result in another one of the existing fountain colors.
The DRIP effect requires parameters to be specified in a thing's ExtraData mapthing block. The parameters to this effect are as follows:
  • args 0: color (palette index from 0 to 255)
  • args 1: particle width/height in pixels
  • args 2: frequency in gametics
  • args 3: if 1, particles cause terrain hits
  • args 4: if 1, particles are fullbright
   # a single effect
   particlefx = ROCKET
   # multiple effects
   particlefx = BFG+GREENFOUNTAIN
   # if there are spaces or disallowed characters, you must use quotations
   particlefx = "BFG + GREENFOUNTAIN"

Graphic Properites

  • translucency
Default = 65536 (100%)
This field allows fine, customizable control over a thing's translucency. This field accepts two types of values. First, it may be given an integer value in the range of 0 to 65536, with 0 being completely invisible, and 65536 being normal. Alternatively, beginning with EDF 1.3, you can provide a percentage value to this field indicating the amount of the foreground sprite that is blended with the background. A percentage value must be a base 10 integer between 0 and 100, with the final digit followed immediately by a '%' character (percent sign).
Note this effect is mutually exclusive of BOOM-style translucency. If this value is not 65536 (or 100%), and the BOOM translucency flag is turned on for the same thing type, the flag will be turned off at run-time, and this field will take precedence.
  • translation
Default = 0
Sets a translation for the thing's sprite. Translation tables are 256-byte lumps which can be used to remap any range of colors in a sprite. When this field defaults, no translation will be used. Otherwise, you may either provide a number to access one of the internal player translation tables, or you may provide the name of a translation lump, which must be found between T_START and T_END markers amongst one of the currently loaded wad files. Numeric values for player translations are as follows. All of the player translations remap the pure green range.
   Number     Color
    1        Indigo
    2        Brown
    3        Red
    4        Tomato
    5        Dirt
    6        Blue
    7        Gold
    8        Felt
    9        Black
    10       Purple
    11       "Vomit"
    12       Pink
    13       Cream
    14       Yellow
  • skinsprite
Default = "noskin"
The skinsprite field defines a sprite that will be used to override the sprite value in any frame a thing of this type enters. This allows the creation of thingtypes which behave identically but look different without the creation of any new frames. Note that when things are crushed into gibs, the skinsprite is cleared at that time. If an Archvile resurrects such a thing, the proper skinsprite is then restored.
  • defaultsprite
Default = NULL
  • alphavelocity
Default = 0.0
If nonzero, the thing's translucency (alpha value) will cycle on and off by this velocity.
  • xscale
Default = 1.0
Sets how much the horizontal component of the sprite is to be scaled.
  • yscale
Default = 1.0
Sets how much the vertical component of the sprite is to be scaled.

ACS Spawn Data Sub-Block

  • acs_spawndata
Default = (nothing)
This specifies the identification number for various parameterized specials that, if ran from the Hexen format, wouldn't support numbers higher than 255. It also limits the number to a game namespace. For example, by default the Zombieman has
acs_spawndata { num 4; modes doom }
Heretic objects will use "modes heretic" instead of "modes doom".