EDF thing reference

From Eternity Wiki
Revision as of 11:05, 16 August 2009 by Printz (talk | contribs) (New page: 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. Each thing type must...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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.

Each thing type must be given a unique mnemonic in its definition's header, and this is the name used to identify the thing type elsewhere. Each field in the thing type definition 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.

If a thing type's mnemonic is not unique, the latest definition of a thing type with that mnemonic replaces any earlier ones. See the information below for more on this. Thing type mnemonics are completely case-insensitive. This means that a thing type defined with a mnemonic that differs from an existing one only by case of letters will overwrite the original type.

Note that the order of thing type definitions in EDF is not important. For purposes of DeHackEd, the number used to access a thing type is now defined in the type itself. For the original thing types, these happen to be the same as their order.

User thing types that need to be accessible from DeHackEd or by parameterized codepointers can define a unique DeHackEd number, which for purposes of forward compatibility, should be greater than or equal to 10000 and less than 32768. User types not needing access via DeHackEd or by parameterized codepointers can be given a DeHackEd number of -1. If a thingtype with a DeHackEd number of -1 is used by name in a misc or args field using the "thing:" prefix, it will be automatically assigned a unique DeHackEd number by the game engine. The previous behavior was to post a warning message and replace the thing with the "Unknown" type. This largely removes the need for users to assign and keep track of DeHackEd numbers.

Syntax

thingtype <unique mnemonic>
{
  inherits        = <thing type mnemonic>
  basictype       = <basic type name>
  doomednum       = <number>
  spawnstate      = <frame mnemonic>
  spawnhealth     = <number>
  seestate        = <frame mnemonic>
  seesound        = <sound mnemonic>
  reactiontime    = <number>
  attacksound     = <sound mnemonic>
  painstate       = <frame mnemonic>
  painchance      = <number>
  painsound       = <sound mnemonic>
  meleestate      = <frame mnemonic>
  missilestate    = <frame mnemonic>
  crashstate      = <frame mnemonic>
  deathstate      = <frame mnemonic>
  xdeathstate     = <frame mnemonic>
  deathsound      = <sound mnemonic>
  speed           = <number> OR <floating-point number>
  radius          = <floating-point number>
  height          = <floating-point number>
  correct_height  = <floating-point number>
  mass            = <number>
  damage          = <number>
  topdamage       = <number>
  topdamagemask   = <number>
  activesound     = <sound mnemonic>
  flags           = <flag list>
  flags2          = <flag list>
  flags3          = <flag list>
  cflags          = <flag list>
  addflags        = <flag list>
  remflags        = <flag list>
  raisestate      = <frame mnemonic>
  translucency    = <number> OR <percentage>
  bloodcolor      = <number>
  fastspeed       = <number> OR <floating-point number>
  nukespecial     = <BEX codepointer mnemonic>
  particlefx      = <particle effect flag list>
  droptype        = <thing type mnemonic>
  mod             = <MOD name> OR <number>
  obituary_normal = <string>
  obituary_melee  = <string>
  translation     = <number> OR <translation table lump name>
  dmgspecial      = <dmgspecial name>
  skinsprite      = <sprite mnemonic>
  dehackednum     = <unique number>
}

Explanation of fields

  • inherits
No default value
Sets the thing type from which this type will inherit values. See the Thing Type Inheritance section below for full information on how thing type inheritance works.
  • basictype
No default value
Sets the basic type of this thingtype definition. Basic types are not thingtypes, but are engine-defined sets of flags and states which an object can adopt as its default values for the corresponding flag and state fields. Use of basictypes is encouraged because thingtypes using them can automatically adapt to occasionally necessary changes to monsters and other thing categories that involve the addition of new thingtype flag values. This is a table of all currently existing basictypes and the values that they impart upon thingtypes:
  • Monster
Purpose: An ordinary walking monster with no fancy features.
cflags = SOLID|SHOOTABLE|COUNTKILL|FOOTCLIP|SPACMONSTER|PASSMOBJ
  • FlyingMonster
Purpose: An ordinary flying monster.
cflags = SOLID|SHOOTABLE|COUNTKILL|NOGRAVITY|FLOAT|SPACMONSTER|PASSMOBJ
  • FriendlyHelper
Purpose: A player helper with maximum friendliness options.
cflags = SOLID|SHOOTABLE|COUNTKILL|FRIEND|JUMPDOWN|FOOTCLIP|WINDTHRUST|SUPERFRIEND|SPACMONSTER|PASSMOBJ
  • Projectile
Purpose: A standard projectile.
cflags = NOBLOCKMAP|NOGRAVITY|DROPOFF|MISSILE|NOCROSS
  • PlayerProjectile
Purpose: A projectile for use by players.
cflags = NOBLOCKMAP|NOGRAVITY|DROPOFF|MISSILE|NOCROSS|SPACMISSILE
  • Seeker
Purpose: A missile prepared to be fired by homing missile codepointers.
cflags = NOBLOCKMAP|NOGRAVITY|DROPOFF|MISSILE|NOCROSS|SEEKERMISSILE
  • SolidDecor
Purpose: A solid decorative item.
cflags = SOLID
  • HangingDecor
Purpose: A hanging decorative item that is passable even without 3D object clipping.
cflags = SPAWNCEILING|NOGRAVITY
  • SolidHangingDecor
Purpose: A solid hanging decorative item.
cflags = SOLID|SPAWNCEILING|NOGRAVITY
  • ShootableDecor
Purpose: A shootable decorative item.
cflags = SOLID|SHOOTABLE|NOBLOOD
  • Fog
Purpose: A fog item such as telefog or item fog.
cflags = NOBLOCKMAP|NOGRAVITY|TRANSLUCENT|NOSPLASH
  • Item
Purpose: A collectable item. Doesn't count.
cflags = SPECIAL
  • ItemCount
Purpose: A collectable item. Counts for item %.
cflags = SPECIAL|COUNTITEM
  • TerrainBase
Purpose: A TerrainTypes base item.
cflags = NOBLOCKMAP|NOGRAVITY|NOSPLASH
  • TerrainChunk
Purpose: A TerrainTypes chunk item.
cflags = NOBLOCKMAP|DROPOFF|MISSILE|LOGRAV|NOSPLASH|NOCROSS|CANNOTPUSH
  • ControlPoint
Purpose: An inert control point.
cflags = NOBLOCKMAP|NOSECTOR|NOGRAVITY
spawnstate = S_TNT1
  • ControlPointGrav
Purpose: An inert control point that is subject to gravity.
cflags = DONTDRAW|NOSPLASH
spawnstate = S_TNT1
  • doomednum
Default = -1
Sets the ID used to identify this thing type in maps. For example, when a map calls for a thing with ID 2003, the game engine will find the thing type which has that number in this field. Every thing that will be spawned on maps must have a unique doomednum. Things which are not spawned on maps, such as fireballs, can be given the default doomednum of -1.
For purposes of forward compatibility, user-defined thing types should use doomednums greater than or equal to 20000 and less than 32768. All other doomednum ranges are considered to be reserved as outlined here. The purposes of various blocks may be relaxed in the future for purposes of internal use, so these are only rough guidelines provided for completeness.
    Doomednum Range     Usage
   ---------------------------------------------------------------
       0                No-op, no thing will be spawned at all
       1 -  4999        Original DOOM things and some extensions
    5000 -  5999        BOOM-style control points
    6000 -  6999        Reserved for port use
    7000 -  7999        Things translated from other games
    8000 -  8999        Reserved for port use
    9000 -  9999        zdoom-style control points
   10000 - 19999        Reserved for port use
   20000 - 32767        Reserved for EDF
  • 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.
  • spawnhealth
Default = 1000
Sets a thing's maximum amount of life. It is only used for things which can be shot.
  • seestate
Default = S_NULL
Sets the frame which a monster will jump to when it sees or hears a target. Also called walking frames, or first moving frame.
  • 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)
  • 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.
  • attacksound
Default = none
Sets a sound used by some monster attacks, including the Lost Soul's charge.
  • painstate
Default = S_NULL
Sets the frame a thing may randomly enter when it has been injured.
  • 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.
  • painsound
Default = none
Sets the sound played by the Pain codepointer when this thing uses it. Monsters and the player always call Pain from their painstate.
  • meleestate
Default = S_NULL
If this frame is not S_NULL, monsters chasing a target will attempt to close to melee range quickly. When they determine they are within 64 units of their target, they may randomly 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.
  • 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.
  • 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.
  • xdeathstate
Default = S_NULL
If a thing dies by taking enough damage that its health is equal to its negated spawnhealth value, it will enter this frame instead of its deathstate. This is also known as gibbing, or extreme death. If this frame is S_NULL, the thing will always die normally.
  • deathsound
Default = none
Sound played by the Scream codepointer. Used to play monster death sounds.
  • 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.
  • 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.
  • 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.
  • 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. New to EDF 1.7.
  • 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.
  • 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.
  • 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 Flag List documentation in the Eternity DeHackEd/BEX Reference, and also see the Bits Mnemonics section 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 Flag List documentation in the Eternity DeHackEd/BEX Reference, and also see the Bits2 Mnemonics section 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 Flag List documentation in the Eternity DeHackEd/BEX Reference, and also see the Bits3 Mnemonics section 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.
  • cflags
Default = ""
New to EDF 1.2, this field allows specification of all the thing's flag values in one single flag list. When this field is defined, the 3 normal flags fields above are ignored. You can use one or the other in any definition, but not both in the same definition. 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 DeHackEd documentation listed in the fields above for full information on flag list format and flag mnemonics.
  • addflags
Default = ""
New to EDF 1.2, 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 = ""
New to EDF 1.2, 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.
  • raisestate
Default = S_NULL
If this frame is not S_NULL, an Archvile can perform a resurrection on this creature. When this occurs, the creature will enter this frame.
  • 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.
  • 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
   --------------------------
   
  • 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.
  • 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.
  • 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
Examples:
   # a single effect
   particlefx = ROCKET
   
   # multiple effects
   particlefx = BFG|GREENFOUNTAIN
   
   # if there are spaces or disallowed characters, you must use quotations
   particlefx = "BFG + GREENFOUNTAIN"
   
  • 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.
  • 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
   BFG11K_SPLASH 21
   BETABFG       22
   BFGBURST      23
   PLAYERMISC    24
   GRENADE       25
   
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.
  • 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".
  • 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
   ------------------
   
  • 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.
  • 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.
  • dehackednum
Default = -1
As explained above, this is the number which must be used to refer to this thing type in DeHackEd patches. -1 means that the thing type is not accessible from DeHackEd. User-defined thing types should currently only use DeHackEd numbers between 10000 and 32768, or simply use -1 if no DeHackEd functionality is required. This number must be unique unless it is -1. As of EDF 1.6, if a thing with a DeHackEd number of -1 is used in a misc or args field, it will be automatically allocated a unique number by the game engine.