Table of Contents

Material (DED)

Definitions specify the properties of a material built from one or more textures, for use on the surfaces of world maps (floors, walls etc…).

The focus of this article is to detail how these properties are exposed to mod authors and the specifics of the syntax.

Core concepts

A material is an abstract concept which replaces the id Tech 1 mechanism of directly attributing texture resources to map surfaces. Please see the material documentation for details on their use(s) and the mechanics of the abstraction with regard to mod compatibility.

Using materials one is able to layer textures in a dynamic, “logical material” which can be applied to a world surface. (In contrast to a texture, which is a static composite of one or more graphics).

Materials exist entirely independently from any textures attributed to their layers. This means one can reuse the same textures in multiple Materials.

Note for modders: The term 'texture' in Doomsday refers to any graphic resource which has been loaded for use as an in-game texture. Graphics composited from several patchs according to TEXTURE1/2 definitions are a type of texture.

Syntax

Material {
  ID = ""
  Width = 0.0
  Height = 0.0
  Flags = flag1 | flag2

  Layer {
    Stage {
      Texture = ""
      Offset { 0 0 }      
      Tics = 0
      Rnd = 0
      Glow = 0.0
      Glow Rnd = 0.0
    }
  }

  Light {
    Pattern offset { 0 0 }
    Pattern skip { 0 0 }  
    Stage {
      Offset { 0 0 }
      Distance = 0.0
      Tics = 0
      Rnd = 0.0
      Color { 0 0 0 }
      Levels { 0 0 }
      Radius = 0.0
      Bottom map = ""
      Side map = ""
      Top map = ""
      Halo radius = 0.0
      Flare map = ""
      Flare texture = 0   # deprecated      
    }    
  }
}

ID

uri by which the material will be known. The ID is used when applying the material directly to a world surface (for example, in a map_editor), or, when referencing it in other definitions. The IDs are considered unique within the defined namespace (i.e., only the latest Material with a given ID will be used).

Currently there are 4 recognized material namespace identifiers:

  • flats
  • sprites
  • system
  • textures

The material documentation details their use and the mechanics of the abstraction with regard to mod compatibility.

Height/Width

The dimensions of the material, in world units.

The material dimensions need not equal those of the texture(s) used by it's layers. Allowing the material to be scaled independently.

Flags

Name Description
dontdraw Surfaces with this material will never be drawn.
skymask Surfaces with this material will cut a “window” through which the sky is visible. The layers of the material itself will never be drawn.

Layer

Currently only 1 layer is supported in a material. (Support for more layers will be added later).

Stage
Stages are used for animating the properties of a texture layer over time. A layer can have many stages and will cycle through each in the defined order.
Texture
uri of the texture resource to use during this stage. For example:
Texture = "Flats:FLOOR4_8";
Offset
Offset to the texture origin in material space.
Tics
Length of the stage in tics.
Rnd
Random value to be applied to tics.
Glow
Strength of the light emitted by this material (self-illumination).
Glow Rnd
Independent glow strength randomization factor.

Light (1.10 →)

doom_light_decorations.jpg Up to 16 light decorations can be attached to the material. Using light decorations one can embellish a material with a wide variety of (possibly animated) lighting effects. The order in which lights are defined does not matter.

For each world surface using the material, Doomsday will automatically project lights into the world relative to the surface normal and according to the repeat pattern you define.

Pattern offset

Used with pattern skip to offset the origin of the pattern. For example: 

Pattern offset { 1 0 }  # shift the origin of the pattern one full horizontal repeat

Pattern skip

Normally the light is repeated on a surface as many times as the texture or flat repeats. The pattern skip values allow sparser repeats for horizontal and vertical patterns, respectively. For example: 

Pattern skip { 1 2 }  #> light appears on every second horizontal repeat
                         and every third vertical repeat. <#

Stage

Stages are used for animating the properties of a light over time. Each light can have many stages and will cycle through each in the defined order.

Using stages it is possible to animate a wide variety of interesting lighting effects.

Tics
Length of the stage in tics.
Rnd
Random value to be applied to tics.
Offset
Origin of the light in material space coordinates.
Distance
Distance of the light from the surface, in world space units. Doomsday will project from the light origin along the surface normal to calculate the 3D position of the light in world space.
Color
RGB color/intensity (values 0-1) of the light.
Radius
Radius of the light in world space.
Levels
Two integers (0-255) that mark the sector light levels where the light is at zero and maximum brightness, respectively. The first level can be higher than the second. The behavior is then reversed: the light is at full brightness only below the lower light level. For example:
  
  Levels { 100 200 }  #> Not visible below light level 100 and fades to
                         full brightness when nearing light level 200.
                         Fully-bright over 200. <#

Note: When both the minimum and maximum values are equal (irrespective of value) the levels will be ignored because the intended behavior is ambiguous.

Bottom/Side/Top map
Name of the light map to use when casting light in that direction. The bottom map is used for floor planes, the top map for ceiling planes and the side map for walls. If left blank (the default), the default linear falloff texture for round lights is used. Use - to disable the map entirely. (No light will then be cast in that direction).
Halo radius
Radius of the halo/flare in screen space. Zero means no halo is rendered.
A halo radius of 1.0 produces quite a large flare!
Flare map
Name of the flare map (i.e., texture) to use for the halo. For example:
Flare map = "myflaremap.png"  # loaded from the data/<game>/flaremaps folder

Alternatively, Doomsday provides a small built-in selection of flare maps, which are specified by their unique ID:

ID Description
0 Smart algorithm which selects a built-in flare map dynamically, according to the attributes of the light and relative position of the viewer.
1 Airy disk corona, with subtle noise.
2 Inverse diffraction disc.
3 22° halo.
4 Burst with cross formation of light pillars.

For example: 

Flare map = "1"  # Use the default, Airy disk style corona.

Flare texture (deprecated)

Built-in flare map (i.e., texture) ID to use for the halo.

2023-03-05 16:32

Examples

A simple 128×128 Material composed of a single non-animated texture layer: 

Material
{
  Id = "Textures:MyMaterial";
  Height = 128;
  Width = 128;
  Layer {
    Stage { Texture = "Textures:BROWN1"; }
  }
}