Overview

Weird Worlds has a robust particle effects system that is used for all the flashy special effects in the game, from weapon muzzle flashes to ship explosions to supernovas. This tutorial will provide a couple of examples of these effects and explain how they work.

There are two main places where you'll find particle effects: the effects.ini in the main gamedata folder, and the .ini files of items that require special effects (weapons and shields).

New: Mods can now include new global special effects in files besides effects.ini, for example effects_ravian.ini. These need to be declared in game.ini.

Global effects

Global particle effects are defined in effects.ini and additional effects files placed in the gamedata folder and declared in game.ini. The ones in effects.ini are universal stuff... Exploding starships, supernovas and so on. If you want to change these, copy the file into your mod's gamedata folder, open it up in your favorite text editor and have a look.

In the file, you'll see a number of "EMIT" entries. These are particle emitters. Each one describes what kind of particles to shoot, which way and how fast. You will notice that occasionally there's more than one with the same name (up to 4). All of those emitters are used at the same time, as is the case with the supernova explosion. There are certain rules for each global effect which we'll cover after looking at this example; behold, the flames that shoot out of a burning ship!

EMIT flamejet
This line gives the particle emitter a name. Any emitter with the name "flamejet" will be used when a ship is on fire. These particles will come out of the visible hardpoints on the ship's hull. See the Starship tutorial on more information about those.

REFR entity
This is the reference location for the particle emitter. When it comes to global effects this has generally no meaning, it's just there to make the emitter entry complete. Maybe I'll do a weapon effect example later, where the reference actually matters (you'll specify whether it's at the muzzle of the gun, or when the weapon impacts something etc).

FILE combat/particle.tga
ANIM 32 32 0
This is the particle's graphic and its animation settings. The numbers are the start and end frames of the animation, and the framerate in frames per second (in this case it's only using one frame so the rate can be set to zero). You'll notice in some cases the framerate is set to -1; this causes the animation to last exactly as long as the lifetime of the particle (like an animated explosion for example). If it's set to -2, a random frame between the start and end is picked but the particle doesn't animate. This is used for the random debris pieces.

When you make new particle sprites, you should put as many of them as possible on one new "sheet" and use the frame numbers to pick which sprite you're using. You should not add them onto the original particle.tga.

Note that particles use "pre-multiplied alpha" for blending. This means glowing particles are simply drawn on black with a totally transparent alpha channel; while opaque or alpha-blended particles will use the alpha channel as opacity. See the Starship tutorial for an example of constructing a 32-bit .tga image in Photoshop.

FLAG zoomin zoomout
The flags change the behavior of the particle in various ways:
relative - if emitted from a combat entity, use relative speed
fadein - particle starts transparent/dark and becomes opaque/bright over time
fadeout - particle fades out to transparent/dark at the end of its life
zoomin - particle starts small and grows to its full size over time
zoomout - particle shrinks down and disappears at the end of its life
slowdown - particle slows down over time, as if by friction
worldtime - use starmap time instead of real time (such as nova shockwave)
rotoffs - causes the OFFS to be rotated by the angle of the particle
trail - turns the particles into a continuous trail

RATE 4
How often a particle is emitted. Specifically how much time there is between particles (in 1/100's of a second). This one shoots one out once every 0.04 seconds.

SIZE 12
Size of the particle sprite (in meters). This is the maximum size it will reach during its life. In this case with the zoomin/zoomout flags, the particle will start with zero size, grow to 12 meters, and then shrink down again.

LIFE 60
Lifetime of the particle (how long it stays visible) in 1/100's of a second (ie. this one lives 0.6 seconds).

OFFS 0 0 0
Location and angular offset (X Y Angle). If these are set to non-zero, the particle will appear "X" meters to the side or "Y" meters forward/back of the reference location, or rotated by "Angle" degrees.
New: Normally the location offset is based on the entity's reference frame, e.g. OFFS 0 -8 0 is always 8 meters back from the center of the entity. If you use the "rotoffs" flag, the location is rotated depending on the angle such that this would mean 8 meters in the direction opposite to the particle's initial direction. For example, this can be used to make (randomly angled) particles appear along a circle around the entity like the "charge-up" effect seen in the superpirate sample mod in v1.2.

SPED 0 40
The X and Y velocity of the particle. X is sideways, Y is forward. A third number can be added to impart an angular velocity (spin).

RAND 0 0 30 0 20
Randomness added to the particle. The first three are randomness of the offset (in this case the particle may be randomly rotated 30 degrees left or right but is never moved right/left or forward/back), then the randomness of speed (this will add or subtract up to 20m/s from the forward speed). A sixth number can be added for randomizing angular velocity.

NUMB 1
How many particles to spew out at once. A "stream" of particles like the fire usually only create one particle at once. Explosions and such may create clouds of particles where the number is higher.

END EMIT This closes the EMIT entry.

List of global emitters in effects.ini

Descriptions of each emitter name and how they're used.

flamejet
Flames that shoot out of ship hardpoints when it's about to explode.

sparkjet
Sparks from destroyed ship systems.

brokenoff
Flames from broken hull pieces

debristrail
A thin trail of fire behind the random "machinery chunks" (below)

debris
Random pieces of machinery that fly out when a ship explodes. Note the "SPEW debristrail" line that refers to the previous particle emitter. The number of debris chunks that actually appear depends on the hull size. These are also used when ships collide.

shipexp
Starship explosion #1. This is the animated explosion sprite that appears on the ship. The size and lifetime are scaled by the hull size divided by 64. For example if a hull 128 meters long explodes, the explosion is twice as big and lasts twice as long as set in this particle emitter.

shipexp2
Starship explosion #2. This is the "shock wave", or ring of white streaks that shoot out in all directions. It's scaled similarly to the previous one, with the addition that the number of particles is also scaled (so the big ship creates more particles).

hyperin
Particles displayed on the starmap when you engage the hyperdrive.

hyperout
Particles displayed on the starmap when you come out of hyperspace at your destination stars. Also used for Klakar arriving in combat.

novasparks
Clouds of fiery plasma spewed out from a nova explosion.

novashock1
Various shockwave effects playing in realtime. One of these is a tiny, invisible particle that stays in place and spews out the aforementioned clouds over time.

novashock2
Nova shockwaves that play out in world time, to visualize the lethal radius of the nova explosion. The lifetime of these particles (in days) is multiplied by the size of the nova in lightyears.

collapser1
Vacuum collapser shockwave, works similarly to the nova.

Note that the emitters systemhit, onfire and shockexp are obsolete and no longer in use. As of v1.2, it is also possible to define burning and explosion effects for each hull. While the above are still used as the "default" effects, a hull can use its own set of effects defined in a separate file. For examples, see the ravian hulls and effects_ravian.ini.

Weapon example

Alright, let's examine a weapon with particle effects and see how they differ from the global effects.ini emitters. For this example I'll use wp_projrail.ini (Neptunium Railgun).

Within the DATA block of the weapon, we find two particle emitters. One thing that's immediately apparent is that they don't have names set on the EMIT line. This is because nothing else refers to these emitters by name. Rather, the reference location determines when these particle effects are used.

The first emitter is the muzzle flash. The animation frame is the familiar fiery globe. Twenty of these are emitted straight ahead at 40m/s velocity with +/-40m/s randomness. This gives us a nice elongated but irregular glob of fire that spews out of the gun barrel. Note the "relative" flag that means the muzzle flash particles are affected by the ship's motion.

EMIT
REFR muzzle
FILE combat/particle.tga
ANIM 32 32 0
OFFS 0 0 0
FLAG relative zoomout
SPED 0 40 0
RAND 0 0 0 0 40 360
SIZE 6
LIFE 50
NUMB 20
END EMIT

The second emitter is the impact effect, so the reference location is set to "impact". This is a very simple animated "spark explosion" with 8 frames. The framerate is set to -1 so it plays exactly once during the 0.3sec lifetime of the particle.

EMIT
REFR impact
FILE combat/particle.tga
ANIM 16 23 -1
SIZE 16
LIFE 30
NUMB 1
END EMIT

List of reference locations

projectile - particles come out of the projectile (like a smoke trail).
impact - particles are triggered when the weapon hits a starship.
expire - particles appear at the end of the projectile's life.
muzzle - particles appear at the muzzle of the gun.
destroy - particles appear if the projectile is shot down by point defense.

Missile trail example

This example is from wp_missfiss.ini, using the v1.2 particle trail effects.

If you were to replace the FILE and ANIM with one of those glowing orbs, and remove the "trail" and "stretch" flags, this emitter would look identical to the old missile trails. Basically, it still emits particles at regular intervals. The new effect simply "connects" those particles with a stretched sprite similar to a beam weapon effect. This allows the game to use fewer particles and still produce a solid trail.

The FILE command loads a sheet similar to what's used for beam weapons. The important part is that graphics/combat/trail.ini sets the graphic to "repeat" just like the beams do. The ANIM frame we're using, however, doesn't tile so we'll be handling this a bit differently.

The FLAG command sets a couple of important flags: trail and stretch. The "trail" flag obviously turns on the beam-like trail rendering. What the "stretch" flag does is stretch the sprite so that its "bottom" is where the trail starts (the missile) and the "top" is where it ends (smoke fading off into space). This allows you to use a trail that changes color from "fire" at the missile to "smoke" further away. Without the stretch, one would have to use a tiling animation frame. See wp_projprot.ini for an example of this.

As with regular particles, the "length" of the trail is determined by how fast the particles move (SPED) and how long they live (LIFE).

EMIT
REFR projectile
FILE combat/trail.tga
ANIM 1 1 0
RATE 20
OFFS 0 -4 180
FLAG relative trail zoomin fadeout stretch
SPED 0 80 0
RAND 0 0 2 0 0 0
SIZE 32
LIFE 180
NUMB 1
END EMIT

Shield "particle" example

Let's take a quick look at sy_shieldelmx.ini (Electron Matrix Shield) and its particle emitter. This emitter is responsible for the shield bubble effect that can be seen when the shield absorbs a weapon hit.

It looks pretty normal but is actually not a real particle emitter at all. When the game is displaying a ship it'll use the data stored in this emitter entry to determine how to draw its shield. Note that the size is a percentage of the hull size, so normally it'll always be 100 for a shield that envelops the whole ship.

EMIT
REFR impact
FILE combat/shield.tga
ANIM 0 0 1
SIZE 100
LIFE 10
NUMB 1
END EMIT

[GO BACK]