Particles In Code

Precaching

Particle systems must be precached before they can be used. This is done by listing the PCF containing them in particles_manifest.txt, then making this call:

PrecacheParticleSystem( "your_particle_effect_name" );

Server

Dispatching

Particles are dispatched as temp ents. The dispatch functions are shared, so there's no need to #ifdef calls out on the client.

#include "particle_parse.h"

// Create at world co-ords
DispatchParticleEffect( "my_particle", vecOrigin, angAngles, pOwnerEntity )

// Create at model attachment
DispatchParticleEffect( "my_particle", ParticleAttachment_t, pOwner, iAttachment, bResetAllParticlesOnEntity  )

See also ParticleAttachment_t, below.

Bug:Valve's code for dispatching a particle on a model attachment is broken. Get the fix here.  [todo tested in ?]

Destroying

StopParticleEffects( CBaseEntity* )

Stops all effects on the given entity.

Client

Creating

Particle systems are automatically created on the client when a dispatch event is received, or can be created manually. Each system is a CNewParticleEffect object managed through the owning entity's ParticleProp() accessor:

#include "particles_new.h"

// Create a new system
CNewParticleEffect* pEffect = ParticleProp()->Create( "my_particles", PATTACH_ABSORIGIN );

// System already exists
CNewParticleEffect* pEffect = ParticleProp()->FindEffect( "my_particles" );

Alternatively, you can hook into particle creation events:

void C_MyEntity::OnNewParticleEffect( const char* pszParticleName, CNewParticleEffect* pNewParticleEffect )
{
	// ...
}

Control points

It is not possible to set the value of control points from the server. On the client, you can with these CNewParticleEffect functions:

SetControlPoint( Vector )

Arbitrary set the CP's value.

SetControlPointEntity( CBaseEntity* )

Follow the given entity's origin.

Confirm:Set to NULL to disable following.

SetControlPointOrientation( QAngle )

SetControlPointRightVector()

SetControlPointForwardVector()

SetControlPointUpVector()

Set orientation with a QAngle or series of Vectors.

Destroying

StopParticleEffects( CBaseEntity* )

Stops all effects on the given entity.

ParticleProp()->StopParticlesInvolving( CBaseEntity* )

Stops all effects with a control point attached to the given entity.

Todo: Global or only on current entity?

ParticleProp()->StopParticlesNamed( const char* )

Stops all effects with the given system name.

Todo: Global or only on current entity?

CNewParticleEffect::StopEmission( bool bInfiniteOnly, bool bRemoveAllParticles, bool bWakeOnStop)

Stops the current particle system, without removing it.

Todo: Meaning of first and third arguments.

ParticleAttachment_t

One of these values is passed when dispatching or creating an effect:

PATTACH_ABSORIGIN

PATTACH_ABSORIGIN_FOLLOW

Spawn at (and optionally follow) the entity's origin.

PATTACH_POINT

PATTACH_POINT_FOLLOW

Spawn at (and optionally follow) an attachment point on the entity's model.

PATTACH_CUSTOMORIGIN

Spawn at a given origin.

PATTACH_WORLDORIGIN

Don't associate with an entity at all. Use with caution - could easily cause memory leaks.