Weird Worlds mod tutorial: Particles
Last updated 11/26/2006
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 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!
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
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).
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
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
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
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 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
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
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.
This closes the EMIT entry.
List of global emitters in effects.ini
Descriptions of each emitter name and how they're used.
Flames that shoot out of ship hardpoints when it's about to explode.
Sparks from destroyed ship systems.
Flames from broken hull pieces
A thin trail of fire behind the random "machinery chunks" (below)
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.
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
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).
Particles displayed on the starmap when you engage the hyperdrive.
Particles displayed on the starmap when you come out of hyperspace at
your destination stars. Also used for Klakar arriving in combat.
Clouds of fiery plasma spewed out from a nova explosion.
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.
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.
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.
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.
ANIM 32 32 0
OFFS 0 0 0
FLAG relative zoomout
SPED 0 40 0
RAND 0 0 0 0 40 360
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.
ANIM 16 23 -1
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).
ANIM 1 1 0
OFFS 0 -4 180
FLAG relative trail zoomin fadeout stretch
SPED 0 80 0
RAND 0 0 2 0 0 0
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.
ANIM 0 0 1