NOD Engine SDK 1.0

NPD File Specifications

Introduction

The NPD file is used to define particle effects. The file extension stands for Nihilistic Particle Definition. The intention of the NPD file was to allow particles to be created and modified using plain text files to set their various parameters. Our first NPD file format for the NOD engine was rigidly based on lines that defined a basic type and then had a variable set of parameters which had to be in the proper order and format. The new format described here changed the file to a simple <keyword,value> pair system that is much less difficult to maintain and easier to understand.

Keywords and values are separated by any whitespace character, such as SPACE or TAB. Lines that begin with ";" are treated as comments and ignored. Blank vertical lines are also ignored. Parameter names are not case sensitive and can appear in any order within a definition. Unlike object templates, there is no inheritance for particle emitters, so any parameters not defined will default to hard-coded values based on the emitter type.

File Format

Each particle emitter defined in the file begins with a type keyword followed by the emitter name. After this name definition, there are a number of optional parameter lines which take the form "keyword value". At the end of the definition, the special keyword "end" appears to mark the end of that emitter’s definition. The valid basic types for the name definition are listed in the table below, followed by the valid parameters and their meanings when used with various emitter types. Some parameters have different meanings when used with different emitter types. Vectors are entered in the file as (X,Y,Z) or (Pitch,Yaw,Roll) as appropriate, including the parentheses.

Emitter Types

Type Keyword

Description

Gas

Emitter clouds that generally forms spheres around the centerpoint

Fire

Similar to gas, but designed for upward drift and turbulence to better simulate fire

Flame

Like fire, but more directed and cohesive, so simulate a single flame or gas torch type of physics

Liquid

An emitter that uses cohesion and streaks to simulate liquid physics

Rain

Used for global weather effects like rain and snow

Sparks

An emitter used to simulate brief emission of hot sparks or electrical sparks

Beam

An emitter that creates a line between two points, such as a laser or plasma stream

Shock

Creates a shockwave effect centered around the origin, normally projecting outward

Ring

An emitter that forms a vertical wall around the origin and typically grows outward

Magic

Particles that move in a somewhat random pattern around an origin to simulate magic effects

Trail

Emitters specifically designed to simulate blade trails or other streaks created by moving objects

Pad

An emitter designed to be attached to the feet of an actor and move with their centerpoint to indicate running effects, etc.

Object

An emitter that creates other object types based on a template name within a certain space at specified frequency

Spurt

A variation on the liquid emitter designed to better simulate blood

Emitter Parameters

Parameter

Emitter Type

Type

Description

Material

All

Name

The material type used to render the particles. The material type defines the texture as well as the blend modes used (via the NAM file format)

MaxParticles

All

Int

The maximum number of particles that can exist. If an emitter birthrate causes the particle count to exceed this level, older particles will be automatically recycled.

Birthrate

All

Int

Average time between new particle creation, in milliseconds

Lifespan

All

Int

Average life of each particle, in milliseconds

StartSize

Most

Float

Initial size of the particles, in game units (22.1 = 1 foot)

StartSize

Shock, Pad

Float

Initial radius of the pad or shockwave effect

StartSize

Rain

Float

For rain emitters, StartSize has a special meaning. It controls the size of the virtual "box" around the camera inside which the particles are created. This box moves with the camera, but the size of the box affects performance and visual density of the effect.

EndSize

Most

Float

Ending size for particles at the end of their lifespan, game units

EndSize

Shock Pad

Float

Ending radius of the pad or shockwave effect

MinDist

All

Float

Minimum distance from center for new particle creation, game units

MaxDist

All

Float

Maximum distance from center for new particle creation, game units

StartColor

All

Hex

Starting color for new colors, as hex ARGB (0xaarrggbb)

EndColor

All

Hex

Color to interpolate to at the end of a particle’s life, in hex ARGB

Gravity

Most

Float

Global acceleration applied to all particles due to gravity. (negative gravity = move upwards) Game units / sec2

Turbulence

Fire, Flame, Beam

Float

Variability in velocity, higher numbers = more variability in motion

EmitShape

Most

Int

Defines the basic shape of the emitter. See separate table for emitter shape information

EmitRadius

Most

Float

Radius of the emitter for emitterShapes that support it. See separate table

EmitHeight

Most

Float

Height of the emitter shape, see separate table

EmitWidth

Most

Float

Width of the emitter shape, see separate table

EmitDir

Most

Vector

Vector that defines the direction for certain emitter shapes, see separate table

MinSpeed

Most

Float

The minimum initial speed for a new particle

MinSpeed

Magic

Float

Minimum rotation speed of the particles around the centerpoint

MaxSpeed

Most

Float

The maximum initial speed for a new particle. If maxSpeed is not specified, it is assumed to be = minSpeed

MaxSpeed

Magic

Float

The maximum rotation speed of the particles around the centerpoint

Drag

Most

Float

The coefficient of drag applied to each particle’s velocity

GrowthRate

Most

Float

Rate of change in particle size over time. Can be positive or negative

Velocity

Flame, Sparks, Spurt

Vector

Initial velocity for newly created particles

Velocity

Rain

Vector

General fall direction of the particles

VelVariance

Rain, Sparks, Spurt

Float

Variability in the fall direction of the particles. Higher numbers = more randomness in the fall velocity

Coehsion

Liquid

Float

Degree of cohesion between multiple particles that form a streak. Higher numbers = greater cohesion of particles

NumGroups

Liquid

Int

Number of streaks to create

MinGroup

Liquid

Int

Minimum number of particles in a streak

MinGroup

Spurt

Int

The minimum group lifespan in seconds

MaxGroup

Liquid

Int

Maximum number of particles in a streak

MaxGroup

Spurt

Int

The maximum group lifespan in seconds

GroupCohesion

Liquid

Float

Degree of cohesion between particles in a group

MinGrowthRate

Magic

Float

Minimum rate at which particles drift from their rotational centerpoint

MaxGrowthRate

Magic

Float

Maximum rate at which particles drift from their centerpoint. Growth rate is randomly selected between min and max.

Flags

Magic

Int

 

MinRadius

Magic

Float

Minimum radius of rotation of particles around the centerpoint

MaxRadius

Magic

Float

Maximum radius of rotation of particles around the centerpoint

RotVel

Shock, Pad

Vector

Rotational velocity for the pad or shock effect, (pitch,yaw,roll)

Count

Shock, Pad

Int

How many times does the effect fire or how many effects are created. (0 = infinite)

Count

Beam

Int

The number of paths to create between the beam endpoints each strike

Length

Rain

Float

Length of each rain particle. Rain particles are actually quads instead of points, so they can have width and height. The texture is stretched to repeat just once for any entered size.

Width

Rain

Float

Width of each rain particle.

MaxStartColor

Ring

Hex

ARGB value for the "maximum" start color. For this emitter, starting particle color is randomly picked between "startColor" and "maxStartColor" to provide extra variability in the colors

MaxEndColor

Ring, Sparks

Hex

ARGB value for the maximum end color

StartHeight

Ring, Sparks

Float

Starting height value for each ring, in game units

EndHeight

Ring

Float

Ending height value for each ring, in game units

NumSegs

Ring

Int

Number of segments to break the ring into. This controls how tessellated the ring shape is when rendered

TextureRate

Ring

Float

How many repeats of the texture to use when texturing the ring. 2.0 = the texture repeats twice in the X axis around the ring diameter

MinBirthRate

Spurt

Float

For some emitters, a range of birthrates can be specified with a min and max, to provide more variability in the frequency of new particle generation

MaxBirthRate

Spurt

Float

The maximum birth rate (higher = slower birth rate) for some emitter types

MinStartSize

Spurt

Float

The minimum starting particle size. Particle sizes are picked randomly between minStartSize and maxStartSize for each particle created. In game units

MaxStartSize

Spurt

Float

The maximum starting particle size, in game units

Template

Template

Name

The name of the template to be created by the emitter

Subtype

Beam

Name

Either "sinus" for a sinusoidal beam, or "noise" for a random beam. Default is noise

UpdateRate

Beam

Int

Milliseconds between updates of the beam positions

Delay

Beam

Int

Milliseconds between re-computations of the beam endpoints

Size

Beam

Float

The distance between each segment of the beam, game units

Frequency

Beam

Float

For sinusoidal beams, the frequency of the waveform used as the basis for the beam

TextureRate

Beam

Float

The slide rate of the texture map on the beam

StartPos

Trail

Vector

The position relative to the center for the start of the trail width

EndPos

Trail

Vector

The position relative to the center for the end of the trail width

Flags

Trail

Hex

If bit 0x1 is set, the emitter is automatically enabled only when the attached actor is attacking

Emitter Shapes

Most emitters can use shape parameters to control the area of emission, to either a 2D shape or a 3D volume. Whenever a shaped emitter is used, the particles are created uniformly within the area or volume.

Emitter Shape

Parameters

0 = Point

Emit particles from a single point, no other parameters are used.

1 = Line

Emit particles from a line. The line begins at the center point and extends to "emitDir".

2 = Disc

Emit particles in a disc shape. EmitRadius defines the radius, height is assume to be zero.

3 = Rectangle

Emit particles in a flat rectangular shape. EmitHeight and EmitWidth define the size of the rectangle centered around the centerpoint.

4 = Sphere

Emit particles in a sphere around the center point. The radius of the sphere is defined by EmitRadius.

5 = Cylinder

Emit particles in a cylindrical shape. EmitRadius defines the radius, and EmitHeight defines the height in the Z-axis.

6 = Box

Emit particles in a box shape. EmitHeight and EmitWidth define the box size, and EmitRadius defines the height of the box.

7 = Ring

Emit particles in a ring shape centered around the centerpoint of the emitter. EmitRadius defines the radius of the ring. EmitHeight defines the height of the ring.

Sample File

gas blueElectricity
material ElectricParticles
lifespan 50
birthrate 50
startsize 25.0
mindist 0.0
maxdist 3.0
startcolor 0xffff80ff
endcolor 0xff200080
minspeed 0.0
maxspeed 0.0
gravity -100.0
growthrate -100.0
turbulence 0.0
end
fire incendExplosion
material fireSprite2
lifespan 250
birthrate 20
startsize 15.0
mindist 0.0
maxdist 10.0
startcolor 0xc0bb3500
endcolor 0x00200000
minspeed 20.0
maxspeed 25.0
turbulence 2.0
end
shock shockflamegreen
material ringOfFire
lifespan 1000
startsize 20
growthrate 150
startcolor 0xff2bf315
endcolor 0x00000000
velocity (0,0,0)
rotvel (0,0,0)
count 1
birthrate 200
end