EDF terrain reference

From Eternity Wiki
Jump to: navigation, search

As of EDF 1.5, the TerrainTypes system has been completely absorbed into EDF. This means it is now possible to completely customize not only what flats are associated with what terrain effects, but the effects themselves. There are three principle object types associated with the TerrainTypes system -- splashes, terrains, and floors. Each will be discussed in its own subsection below.

Back to EDF

Splash Objects[edit]

Splash objects define the thingtypes, sounds, and other properties of a splash caused by an thing hitting a terrain. Not all terrains must have splashes, and each terrain can only refer to one splash object. A splash object itself defines properties for both a low mass and high mass splash, however. All fields in the splash block are optional, and as usual, order is irrelevant.

All splash blocks must have a unique mnemonic. Non-unique mnemonics will overwrite, meaning that the properties of the last splash block encountered with a given name will become the final properties of that splash object.

Syntax[edit]

splash <unique mnemonic>
{
  smallclass  <thingtype mnemonic>
  smallclip   <number>
  smallsound  <sound mnemonic>
  baseclass   <thingtype mnemonic>
  chunkclass  <thingtype mnemonic>
  sound       <sound mnemonic>
  
  chunkxvelshift  <number>
  chunkyvelshift  <number>
  chunkzvelshift  <number>
  chunkbasezvel   <number>
}

Explanation of Fields[edit]

  • smallclass
Default = No object will be spawned
This field specifies the thingtype spawned by a low mass splash (objects of mass less than 10 cause low mass splashes if possible). If this field is unspecified or is an invalid thing type, low mass splash objects will not spawn for any terrain that uses this splash object.
  • smallclip
Default = 0
This field specifies an amount of floorclip in units to add to the low mass splash object. This allows use of objects that would otherwise look incorrect for low mass splashes by making them appear smaller. A typical value for this field is 12 units.
  • smallsound
Default = "none"
The sound specified in this field will be played by mnemonic whenever a low mass splash occurs, independent of whether a valid smallclass is defined. This means you should always define the smallsound field if sounds are desired, even if its value is the same as the sound field. Otherwise, no sound will be played for low mass splashes.
  • baseclass
Default = No object will be spawned
This field specifies the thingtype spawned as the base of a normal splash. If this field is unspecified or is an invalid thing type, no splash base will be spawned for any terrain that uses this splash object.
  • chunkclass
Default = No object will be spawned
This field specifies the thingtype spawned as a chunk thrown upward from the point of a normal splash. The velocities given to this object when spawned are randomized and are customized via the chunk?velshift and chunkbasezvel fields below. If this field is unspecified or is an invalid thing type, no splash chunk will be spawned for any terrain that uses this splash object.
  • sound
Default = "none"
The sound specified in this field will be played by mnemonic whenever a normal splash occurs, independent of whether a valid baseclass or chunkclass is defined.
  • chunkxvelshift
Default = -1
When set to a positive value, this field indicates a value 2^N by which to multiply a randomized number used as the x axis velocity of the splash chunk object. When set to -1, the splash chunk will be given no x velocity.
  • chunkyvelshift
Default = -1
When set to a positive value, this field indicates a value 2^N by which to multiply a randomized number used as the y axis velocity of the splash chunk object. When set to -1, the splash chunk will be given no y velocity.
  • chunkzvelshift
Default = -1
When set to a positive value, this field indicates a value 2^N by which to multiply a randomized number which is added to the chunkbasezvel, the sum of which becomes the z velocity of the splash chunk object. When set to -1, no randomized addend will be used.
  • chunkbasezvel
Default = 0
When set to a positive value, this field indicates a base amount of z velocity to apply to the splash chunk object. The randomized value determined by chunkzvelshift is then added to this base amount of velocity. If set to zero while the chunkzvelshift value is set to -1, the splash chunk object will be given no z velocity.

Restrictions and Caveats[edit]

  • All splashes must have a unique mnemonic no longer than 32 characters. They should only contain alphanumeric characters and underscores. Length will be verified, but format will not (non-unique mnemonics will overwrite previous definitions).

Replacing Existing Splashes[edit]

To replace the values of an existing EDF splash definition, simply define a new splash with the exact same mnemonic value (as stated above, all splashes need a unique mnemonic, so duplicate mnemonics serve to indicate that an existing splash should be replaced).

Full example[edit]

// The Water splash object as defined in terrain.edf demonstrates a 
// fully-defined splash object:

splash Water
{
  smallclass EETerrainWaterBase
  smallclip  12
  smallsound eedrip
  
  baseclass  EETerrainWaterBase
  chunkclass EETerrainWaterSplash
  sound      gloop   
  
  chunkxvelshift 8
  chunkyvelshift 8
  chunkzvelshift 8
  chunkbasezvel  2
}

Terrain Objects[edit]

Terrain objects define the full properties of a TerrainType which can be assigned directly to multiple flats. Terrains may optionally define what splash object they use, as well as values related to inflicting damage, whether or not the terrain is liquid, whether or not hitting the terrain causes enemies to awaken, and other important information. All fields in the splash block are optional, and as usual, order is irrelevant.

All terrain blocks must have a unique mnemonic. Non-unique mnemonics will overwrite, meaning that the properties of the last terrain block encountered with a given name will become the final properties of that terrain object.

Terrain deltas are also supported for editing the properties of existing terrain objects without duplicating all fields within them. See the EDF delta structures section for full information.

Syntax[edit]

terrain <unique mnemonic>
{
  splash          <splash mnemonic>
  damageamount    <number>
  damagetype      <MOD name>
  damagetimemask  <number>
  footclip        <number>
  liquid          <boolean>
  splashalert     <boolean>
  useptclcolors   <boolean>
  ptclcolor1      <palette index> OR <RGB triplet>
  ptclcolor2      <palette index> OR <RGB triplet>
  minversion      <number>
}

Explanation of Fields[edit]

  • splash
Default = No splash is used by this terrain
This field specifies what splash object, if any, to use when objects strike a floor using a flat that is associated with this terrain object.
  • damageamount
Default = 0
This field specifies the amount of damage this terrain inflicts on players at each damage opportunity (determined by the damagetimemask field below). If this field is zero, no damage will be inflicted.
  • damagetype
Default = "UNKNOWN"
Defines the Means of Damage flag used when this terrain damages a player. Values of interest to terrain are typically SLIME and LAVA. Eventually, LAVA will cause thing types which define a special flaming death frame to enter that frame. Please keep this in mind for forward compatbility. Other values for the Means of Death flag can be found in the thingtype section.
  • damagetimemask
Default = 0
Sets the interval at which this terrain will inflict damage on players. This value is applied as a mask to the current level time, so to be most meaningful, this value must be a power of two minus one. A few valid values are 1, 3, 7, 15, and 31. Most DOOM nukage sectors use a mask of 31 as an example, and thus damage the player every 32 gametics, or approximately once per second.
  • footclip
Default = 0
This value defines the amount of footclip in units that this terrain applies to objects standing on it that have the flags2 bit FOOTCLIP set in their options. A footclip of zero means no footclipping is applied. Some special objects may set their own footclip values and thus may not be affected by terrain footclipping in any case. Footclipping is generally only proper for liquid terrain.
  • liquid
Default = false
Specifies whether or not this terrain is liquid. Currently the only effect controlled by this field is suppressing player "oof" sounds when landing on liquid terrains, under the assumption that a splash sound will playing instead. In the future, certain special Heretic objects will react specially to liquid terrain.
  • splashalert
Default = false
Specifies whether or not this terrain causes a noise alert to propagate when a player hits a floor using this terrain. Setting this field to true means that a player hitting the given floors will cause enemies to awaken and begin chasing him. By default, DOOM terrain types do not do this, and Heretic terrain types do.
  • useptclcolors
Default = false
When set to true, this terrain object wants to use customized particle colors when gunshots and certain other effects strike the floor or ceiling of a sector using a flat with which this terrain is associated. Terrains which set this value to false will have their ptclcolor1 and ptclcolor2 fields ignored and will use the default gray bullet puff effects.
  • ptclcolor1
Default = 0
This field may specify either a raw palette index from 0 to 255, or an RGB triplet string in the format "r g b", with each of r, g, and b being a number from 0 to 255. When an RGB triplet is specified, EDF will attempt to match the specified color to the closest color in the game's main palette. If no suitable match can be found, color zero will end up being chosen. For terrain effects that must work across multiple games, you should always utilize RGB triplets. Otherwise, palette indices are more accurate. This value is ignored if useptclcolors is false for this terrain object. This color is typically the darker of the two particle colors used for terrain effects.
  • ptclcolor2
Default = 0
This field may specify either a raw palette index from 0 to 255, or an RGB triplet string in the format "r g b", with each of r, g, and b being a number from 0 to 255. When an RGB triplet is specified, EDF will attempt to match the specified color to the closest color in the game's main palette. If no suitable match can be found, color zero will end up being chosen. For terrain effects that must work across multiple games, you should always utilize RGB triplets. Otherwise, palette indices are more accurate. This value is ignored if useptclcolors is false for this terrain object. This color is typically the lighter of the two particle colors used for terrain effects.
  • minversion
Default = 0
This field controls the minimum demo version in which this terrain object is usable. This field is unnecessary for the majority of user-created terrain objects, and this value should not be edited in the default terrain objects, neither via overriding nor terraindeltas, if your project is meant to function in the presence of old demos. minversion for the default objects is the first Eternity Engine version in which that terrain appeared.

Restrictions and Caveats[edit]

  • All terrains must have a unique mnemonic no longer than 32 characters. They should only contain alphanumeric characters and underscores. Length will be verified, but format will not (non-unique mnemonics will overwrite previous definitions).
  • The default terrain called "Solid" is defined internally by the game engine, but can be edited by creating a terrain named "Solid" in EDF. This should be done with caution, however, since the default terrain is used in all circumstances when no terrain effects are usually expected. The Solid terrain has default values for all fields.

Replacing Existing Terrains[edit]

To replace the values of an existing EDF terrain definition, simply define a new terrain with the exact same mnemonic value (as stated above, all terrains need a unique mnemonic, so duplicate mnemonics serve to indicate that an existing terrain should be replaced).

Full Example[edit]

// The Water terrain object as defined in terrain.edf demonstrates a 
// typical terrain object:

terrain Water
{
  splash   Water
  footclip 10
  liquid   true
  
  useptclcolors true
  ptclcolor1    "127 127 255"
  ptclcolor2    "0 0 255"
  
  minversion = 329
}

// This terrain defines damage properties only to create an 
// instant-death floor type:

terrain SuperDeadly
{
  damageamount   10000  // inflict telefrag damage
  damagetype     LAVA   // use LAVA MOD
  damagetimemask 1      // inflict damage more or less constantly
}

Floor Objects[edit]

Floor objects associate a terrain with a flat graphic. All fields in the floor block are optional, and as usual, order is irrelevant. Floor objects are precisely equivalent to entries in the old, obsolete binary TERTYPES lump, and in fact, TERTYPES is still supported for legacy projects, and will be used to generate additional floor objects if it is found. See the TERTYPES Lump Processing section below for more information.

Multiple floor objects may associate the same flat with different terrains. The last such definition encountered will determine what terrain the flat uses.

Syntax[edit]

floor
{
  flat     <string>
  terrain  <terrain mnemonic>
}

Explanation of Fields[edit]

  • flat
Default = "none"
This field determines the flat to which this floor object's terrain is applied. If a terrain has already been applied to this flat, the terrain specified in this object will override the previous definition. This field need not refer to a valid flat name. No error will occur if the flat specified does not exist; this object will simply have no effect. However, the string specified in this field must be no longer than eight characters or an error will occur.
  • terrain
Default = Solid
This field specifies the mnemonic of the terrain to associate with the flat named in this floor object. As mentioned in the terrain section above, the default Solid terrain type is defined by the game engine. By default, all floors are associated with the Solid terrain. The terrain mnemonic need not be a valid terrain. If it is invalid, a warning will be issued to the verbose EDF log file and the floor object will be modified to use the Solid terrain object.

Full Example[edit]

// A couple of the floor objects defined for DOOM in terrain.edf:
floor { flat FWATER1; terrain Water }
floor { flat LAVA1;   terrain Lava  }

TERTYPES Lump Processing[edit]

As of 3.39.20 TERTYPES lumps are no longer processed.