PARTICLE EDITOR

 In the idTech 5 engine, particle effects are used to simulate the appearance of fire, smoke, weather, weapon impacts, etc.  When there is a need to show an interaction between objects, or to enhance the visibility of actions in a game scene, you will often call upon particle effects to do the job.  In its simplest form, a particle is merely a point that moves through 3d space, represented by some geometric shape, most commonly a quad, and rendered with a special material or shader.

 

 

 In the image above, the first box shows which particle system is selected or being edited. Clicking the '...' will bring up the media browser to create a new particle system. You will notice that when you select a particle system, an interactive node will show up on the left side of the editor. Clicking on each of the buttons or on the node itself will change the 'Properties' window to that which is selected.

 Click on the area on the node at the top where it says "stage 0". You will see Stage properties will show up on the right. This is for editing the various stages of the particle effect. Most particle effects only have one stage, but you can have as many stages as you want. Each stage is almost like an entire particle effect in itself, but all the stages share some common properties like attachment point and direction. The best demonstration of this is the particle effect on a smoking barrel. You see some normal black smoke, but also a little bit of fire and some little ashes that drift away with the smoke. This effect is created with three different stages, one for each of the effects mentioned. 

 You can copy and paste nodes to create stages, right click and select duplicate stage to duplicate the stage, or select Remove Stage to remove it. Right clicking on the node will also allow you to add new properties.

 

Particle Decls

 Particle systems are defined within particle decl files (.prt), contained in the base/particles/ directory. Each particle file can contain multiple particle decls.  A particle decl is composed of one or more particle stages, each with independent properties for defining a group of particles. For example, a basic fire particle decl might contain three stages: a stage for flames, a stage for smoke, and a stage for small embers. 

Using Particle Decls

 Particle decls can be referenced by the game through a number of methods including emitter entities, the FX system, or animation events. 

            Emitter Entity

 The most basic way to spawn a particle system in the game is to use a func_emitter entity placed in the world using World Edit. By default, these entities will spawn the particle system at load-time unless the "startOff" flag is set. You can use the entity color tool to tint the entire emitter with a specific color. This is useful for matching dust particles with the environment, steam particles with lighting, etc. 

            FX System

 One of the most common methods for spawning particle systems in the game is the robust and flexible FX System. Particle systems can be spawned in a variety of ways using the FX System and FX decls. Consult the FX System documentation for more detailed information. 

            Animation Events

 Using the Model Editor, particles can be spawned on joint tags on animated entities using ae_declParticle animation events, or through the FX System using ae_declFX events.  More information can be found in the Model Editor documentation. 

 For a more in-depth look at implementing particles, look at the tutorial for particle systems.

Smoke System

 All particle systems are computed in local-space. That is, the space relative to the particle model's rotation and scale. This behavior is fine for most cases like bullet impacts, ambient effects, etc.  For occasions where this behavior is not acceptable, we have a system in place to spawn particles in world-space, called the Smoke System. 

 The Smoke System can be thought of as a large model that exists in the world, which we can add triangles to as needed. Dust trails on vehicles, flaming debris, and rocket trails are all examples of cases where you would use the smoke system. The Smoke buffer is of a finite size (approximately 2048 particles), which covers all smoke-system particles that exist at any given frame. If the game attempts to create particles exceeding the maximum count, new particles will not be created until previously created particles have been removed from the system. 

 Smoke System particles can be spawned optionally from particle emitter entities, the FX System, and directly through code. When using smoke particles, the spawn rate/count will be ignored and they will be spawned based on a specified rate (one particle every n frames). The smoke system does not work on a per-stage basis. All stages within a particle decl will use the Smoke System if it is enabled for that entity. 

 

 Particle Stage Basics

 This section will provide a brief overview of the most important aspects of a particle decl stage. (referencing the image above) 

Material

 The name of the material decl used for particle.

Orientation Type

 The type of geometry used for rendering the particle. 

Direction

Direction controls the direction the particles move in. The options are Cone, Outward, and Speed. 

Distribution

This controls the area in which the particles are initially spawned. Rect, Cylinder, and Sphere select the shape of the spawn area, and XSize, YSize, ZSize change the size of the spawn area in each of the three axis. 

Ring (which is only available for cylinder and sphere) will cause the particles to form in a ring pattern. 

The number specifies the inner radius of the ring, the outer radius is defined by the size values above it. 

Offset moves the entire area over by some amount (this is most useful when creating a multi-stage effect). 

Unchecking random distribution will cause all the particles to spawn from the same place (at offset + [xsize, ysize, zsize]).

 

Static Mesh

 Particles can also be represented by a custom static mesh instead of generated quads. There are a few considerations to be made when using static mesh particles. 

Considerations

 When importing a static mesh particle, the particle system will process the model such that it is internally represented as a quad list instead of a triangle list. This is because that the particle system and transparency system all work based on quads. After conversion, a file will be written to your generated folder with the “.pmodel” extension. 

 Individual particles are limited to no more than 128 vertices.  Given that the system internally converts the static mesh to quads, the static mesh chosen should be carefully constructed with this limitation in mind. Best case, the system will generate [number of triangles / 2] quads, worst case will generate [number of triangles quads]. 

 To stay within the 128 vertices per particle cap, it is wise to make models with no more than 32 triangles. Worst case 1 quad per triangle = 1 * 32, 4 vertices per quad = 32 * 4 = 128.  You must specify the material explicitly in the particle stage; the particle engine will not read surface paths from the .lwo model format. Static mesh particles can use the View or XYZ orientation types. 

Additional Stage Considerations 

• Particle stages are limited to 128 particles (or 512 vertices, given particles are made of quads)
• Particle stages are sorted top-to-bottom in the particle decl file. Stages will draw in front of previously defined stages, with a few exceptions (Smoke system, transparency sort system) 

Material Animation

 In addition to the standard texture mapping, particles can use animated multi-frame textures. By default, the system assumes animated textures to be composed of a series of frames in a single row, with the animation playing in a single cycle across the duration of the particle's life. Animation frames will be blended (cross-faded) unless the feature is disabled on a per-stage basis.  The following is a brief overview of the animation properties. 

Animation Frames

 Number of frames in the texture sheet. When using a texture with multiple rows, this property defines the number of columns in the texture. You can specify the start frame of the animation explicitly, or use a random start frame. 

Animation Rows

 Number of rows in the animation. You can also treat each row as an independent strip, and pick a random row for each particle, using the "Use Random Row" property. 

Animation Type 

 

 

Transparency Sort

 In most cases particles are drawn and sorted in a fairly standard way. Stages are sorted as a group, and generally drawn on top of previously defined stages. In the case where you need particles to sort per-particle, the transparency sort system must be used. Consult the transparency sort documentation for more specific information.