Table of Contents

Generator (DED)

In Doomsday all particle effects are controlled by the particle subsystem. The particle subsystem's job is to keep track of all the particle effects. Each effect can be made up of one or more particle generators that are bound to a source. Doomsday offers several different choices for the source (e.g., mobj), which is used by the particle system to “trigger” the generators to be spawned when needed. A generator must have a source to be able to create new particles. If the source of a generator is destroyed before the generator dies, the only result will be that no new particles are created. Any existing particles created prior to the removal of the source will live on.

Limitations

There is a limit to the number of active particle generator entities in the level (currently 512). If the maximum number is reached, existing non-static generators will be destroyed to make room for any new generators.

Triggers

There are several methods of triggering a generator, each of which is outlined below:

Method Name Description
Damage Spawn a generator when the specified mobj is damaged.
Flat Spawn a generator when a map surface's material changes.
Map Spawn a generator when the specified map begins.
State Spawn a generator when a mobj enters the specified state.
Type Share a single generator among all mobjs of the specified type.

Syntax

[Copy] Generator {
  State = "";
  Flat = "";
  Mobj = "";
  Alt Mobj = "";
  Damage Mobj = "";
  Map = "";
  Flags = flaga | flagb | flagc;
  Speed = 0.0;
  Speed Rnd = 0.0;
  Vector { 0.0 0.0 0.0 }
  Vector Rnd { 0.0 0.0 0.0 }
  Init Vector Rnd = 0.0;
  Center { 0.0 0.0 0.0 }
  Submodel = -1;
  Spawn Radius = 0.0;
  Min Spawn Radius = 0.0;
  Distance = 0.0;
  Spawn Age = 0;
  Max Age = 0;
  Particles = 0;
  Spawn Rate { 0.0 0.0 0.0 }
  Spawn Rnd = 0.0;
  Presim = 0;
  Alt Start = 0;
  Alt Rnd = 0.0;
  Force = 0.0;
  Force Radius = 0.0;
  Force Origin { 0.0 0.0 0.0 }
  Force Axis { 0.0 0.0 0.0 }
  Stage {
    Type = "";
    Tics = 0;
    Rnd = 0.0;
    Color { 0.0 0.0 0.0 }
    Radius = 0.0;
    Radius Rnd = 0.0;
    Flags = flaga | flagb | flagc;
    Bounce = 0.0;
    Gravity = 0.0;
    Force { 0.0 0.0 0.0 }
    Resistance = 0.0;
    Spin Resistance { 0.0 0.0 }
    Frame = "";
    End Frame = "";
    Spin { 0.0 0.0 }
    Spin Resistance { 0.0 0.0 }
    Sound = "";
    Volume = 1.0;
    Hit Sound = "";
    Hit Volume = 1.0;
  }
}

State

Makes this a state triggered generator. Whenever a mobj is set to this state, a new particle generator is spawned. If the spawn flag is set, the generator is only spawned when the source mobj itself is being spawned (handy if the mobj has a loop of states and the generator should only be spawned when the state is first set).

Flat

Makes this a flat triggered generator. Each plane with the given flat receives its own generator. Flags can be used to control where the particles are actually spawned.

Mobj

Makes this a type triggered generator. The value must be a defined thing ID (e.g., “PLAYER”). All type triggered generators are spawned in the beginning of a level, and they create particles using all mobjs of the given type as sources. Use the static flag to prevent the generator from being removed by later generators (could happen when the maximum number of generators is reached).

Alt Mobj

Alternate mobj type for type triggered generators.

Damage mobj

Makes this a damage triggered generator. The generator is spawned when a mobj of the specified type receives damage. The initial movement direction is calculated from the relative positions of the mobjs involved in the operation, so that positive speed values will make the particles move away from the inflictor (in the direction of the damage).

Map

Makes this a map triggered generator. The generator is spawned only in the specified map (e.g., “E2M3”). The Center defines the spawn origin.

Flags

Flag Description
static Generator will not be removed until it times out. Otherwise it might get replaced by newer generators if there are too many active generators.
extra State triggered: This generator is to be spawned simultaneously with the previously defined generator. This allows having multiple generators assigned to the same state. If this flag is not used, all the previously defined generators associated with the state are ignored.
srcvel State/Type triggered: Particles inherit their source's velocity (in addition to spawn velocity).
srcdir State/Type triggered: Particle movement vector is rotated using source's direction angle.
spawn Generator is only spawned if the source mobj is being spawned.
blendadd or blend Particles of the generator are rendered using additive blending.
blendrsub Particles of the generator are rendered using reverse subtractive blending (framebuffer - particle).
blendsub Particles of the generator are rendered using subtractive blending (particle - framebuffer).
blendmul Particles of the generator are rendered using multiplicative blending (particle * framebuffer).
blendimul Particles of the generator are rendered using inverse multiplicative blending ((1 - particle) * framebuffer).
modelonly The particle generator will only be active if the source is represented by a 3D model.
floor Flat triggered: Particles of the generator will be created on the floor of the source sector.
ceiling Flat triggered: Particles of the generator will be created in the ceiling of the source sector.
space Flat triggered: Particles of the generator will be spawned at a random height in the sector.
density Flat_triggered: Particles specifies the maximum density of particles per block (128×128) rather than the maximum number of particles for the generator.
group Flat triggered: The generator will by used for all flats which share the same group. Useful when defining generators for lava, water, etc…, special effects.

Speed

Initial speed for new particles.

Speed Rnd

Randomness of initial particle speed [0..1]:

  • 0 = Not random at all.
  • 1 = Randomly scaled between zero and the value of Speed.

Vector

Initial movement direction for new particles.

Vector Rnd

Randomness of initial particle direction. Random components of the given value are added to Vector. For example, if Vector Rnd is 2, a random vector with components ranging from -2 to 2 is added to Vector.

Init Vector Rnd

One-time random component applied to Vector when the generator is spawned. Works the same as #Vector Rnd but only applied once.

Center

State/Type triggered: An offset to the source coordinates.

  • X = Distance on the XY plane (world units), rotated using source angle.
  • Y = Source angle offset (degrees).
  • Z = Z distance (positive is upwards, world units).

Map triggered: Origin of the generator (X, Y, Z) in the map's coordinate space.

Submodel

State/Type triggered: If the source is represented by a 3D model, this submodel's center will be used as the origin of the generator. If less than zero, the source's actual coordinates are used and the model has no effect on the origin's position.

Spawn Radius

Particles will be spawned at a random distance from the center of the source, at a distance of at most this many units. A flat distribution inside a cube is used if the Min spawn radius is zero.

Min Spawn Radius

Particles will be spawned at least this many units away from the center of the source. Setting this to a nonzero value will enable the more advanced algorithm for choosing particle spawn coordinates: a random point is chosen inside a sphere with the radius of Spawn radius, but not closer than Min spawn radius.

Distance

Maximum distance at which the particles of the generator are visible. If zero, there is no distance limitation.

Spawn Age

Number of tics that the generator will create new particles after having been spawned. If -1, the generator will continue creating new particles until destroyed.

Max Age

Maximum generator lifetime, in tics. If -1, the generator will not be destroyed until either replaced by a newer generator or the level ends.

Particles

Maximum number of particles that the generator can have, or the maximum density of particles per 128×128 block (with flat triggered generators using the density flag).

Spawn Rate

Number of new particles spawned per game tic. Fractional values are allowed (< 1.0).

Spawn Rnd

Randomness of spawn rate (between 0 and 1):

  • 0 = Not random.
  • 1 = Spawn rate is randomly scaled between zero and the value of Spawn rate.

Presim

Number of tics to “think ahead” when the generator is spawned. Useful with flat triggered generators that are visible right after starting a map.

Alt Start

Index number of the alternative particle start stage. By default all particles start from stage zero.

Alt Rnd

Randomness of initial particle stage (between 0 and 1):

  • 0.0 = Default stage (zero) is always used.
  • 0.5 = 50% chance of starting with Alt start.
  • 1.0 = Always start from Alt start.

Force

Strength of the sphere force that pulls or pushes particles towards the surface of the sphere. In most cases the value should be less than one.

Force Radius

Radius of the sphere for sphere force. The force will push or pull particles to the surface of this sphere, centered around the center of the generator (with the offset specified with Force origin applied).

Force Origin

Defines the coordinates for the force sphere in relation to the center of the source.

Force Axis

The sphere force can also rotate particles around an axis. The length of the axis defines how strong the rotation is.

Stage

Each generator can have many particle stages. Each particle will go through the defined stages starting from zero or the alternative start stage.

Type
Specifies the type of a particle during this stage.
Identifier Description
line Render particle as a line. The length of the line is determined automatically according to the speed of the particle.
point Render particle as a point.
texNN Render the particle as a point-sprite using a texture loaded from the “data/<game-module>/textures/” directory, where the file name is particleNN.ext. For example: “tex01”particle01.png
modelNN Render the particle as a model using the definition with ID ParticleNN.
Tics
Number of tics that the particle will spend in this stage.
Rnd
Randomness of stage tics [0..1].
Color
RGBA color of the stage (each component in the range [0..1]). The fourth component of the color vector is the alpha component (1 = opaque, 0 = fully transparent).
Radius
Radius of the particle at this stage, in world units. The visible radius is interpolated between the radii of the current stage and the next one.
Radius Rnd
Randomness of particle radius. The radius of a particle during this stage will be chosen randomly from the range: [ ((1 - RadiusRnd) x Radius) .. Radius ]
Flags
Flags affecting the particle stage:
Flag Description
stagetouch When touching a wall or a plane, the particle will immediately skip to the next stage.
stagevtouch Same as stagetouch but only applies to walls.
stagehtouch Same as stagetouch but only applies to floor/ceiling planes.
dietouch Particle will die when it touches a wall or floor/ceiling plane.
bright Particle color is not affected by the light level of the sector it is in.
flat When touching a wall or floor/ceiling plane, the particle is drawn flat against the surface.
vflat Same as flat but only applies to walls.
hflat Same as flat but only applies to floor/ceiling planes.
force Particle is affected by the sphere force.
zeroyaw Set particle yaw to zero.
zeropitch Set particle pitch to zero.
rndyaw Set particle yaw to a random value.
rndpitch Set particle pitch to a random value.
Bounce
Determines how 'bouncy' the particle is [0..1]. Note that particles will only collide with walls and floor/ceiling planes.
0 = Particle loses all its momentum when it hits something (in the direction of the collision).
1 = Particle retains all its momentum and continues moving in the opposite direction after a collision.
>1 = Particle gains extra speed in collisions.
Gravity
Determines how strong an effect gravity has on the particle. The default factor is 1.0.
Force
A linear force that affects the particle during this stage, applied independently of sphere force. Tip: A gravity factor of 1.0 is equivalent to Force { 0 0 -1 }
Resistance
Air resistance for the particle [0..1]:
0.0 = Particle moves without friction.
0.5 = Particle loses half of its momentum each tic.
1.0 = All movement of the particle will stop in one tic.
Spin Resistance
Spin resistance for the particle (yaw and pitch, respectively) [0..1]:
0.0 = Particle spins without resistance.
0.5 = Particle loses half of its spin velocity each tic.
1.0 = All spin velocity of the particle will be lost in one tic.
Frame
First model frame in the animation sequence of a model particle. The animation will interpolate through all the frames between this and End frame.
End Frame
Last model frame in the animation sequence of a model particle.
Spin
Model particle spinning velocity (yaw and pitch, respectively) in degrees per second. Each particle will randomly change the sign of the spinning velocity when the particle is first spawned.
Sound
ID of the sound to play when a particle enters this stage. Sound will use the particle's coordinates as its origin.
Use carefully as starting a lot of sounds is a heavy operation.
Volume
Volume of Sound [0..1].
Hit Sound
ID of the sound to play when a particle hits a surface while in this stage. The sound will use the particle's coordinates as its origin.
Use carefully as starting a lot of sounds is a heavy operation.
Hit Volume
Volume of Hit sound [0..1].
2023-03-05 16:32

See also