Difference between revisions of "Particles In Code"

From Valve Developer Community
Jump to: navigation, search
(Added notes about including particle header files, as this caught me out.)
(Dispatching: only works on server)
Line 13: Line 13:
 
=== Dispatching ===
 
=== Dispatching ===
  
Particles are dispatched to clients as [[Temporary Entity|temporary entities]]. The dispatch functions are [[Shared code|shared]], so there's no need to <code>#ifdef</code> calls out on the client.
+
Particles are dispatched to clients as [[Temporary Entity|temporary entities]]. The dispatch functions are [[Shared code|shared]], but only have an actual effect when called from the server.
 
 
When dispatching particle effects, '''particle_parse.h''' must be included in your source file.
 
  
 
<source lang=cpp>
 
<source lang=cpp>

Revision as of 10:20, 31 May 2010

This page details the management of "Orange Box" particles in C++ code. It does not cover the old, hard-coded particle tech.

Precaching

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

PrecacheParticleSystem( "your_particle_effect_name" );

Server

Dispatching

Particles are dispatched to clients as temporary entities. The dispatch functions are shared, but only have an actual effect when called from the server.

#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.
  • vecStart, taken by some overloads of DispatchParticleEffect(), defines the location of control point 1. If you don't specify vecStart, the value of vecOrigin is used instead.
Bug.png Bug: Valve's code for dispatching a particle on a model attachment is broken. Get the fix here.

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"

C_MyEntity::MessWithParticles()
{
	// Create a new system
	CNewParticleEffect* pEffect = ParticleProp()->Create( "my_particles", PATTACH_ABSORIGIN );
	
	// System already exists
	CNewParticleEffect* pEffect = ParticleProp()->FindEffect( "my_particles" );
}

Particles_new.h must also be #included here.

Alternatively, you can hook into particle creation events:

void C_MyEntity::OnNewParticleEffect( const char* pszParticleName, CNewParticleEffect* pNewParticleEffect )
{
	if ( V_strcmp(pszParticleName, "target_effect_name") == 0 )
	{
		// Do something
	}
}
Warning.png Warning: A dispatch message from the server configures both control point 0 AND 1. The values are applied after OnNewParticleEffect() is called, so don't bother trying to assign either of those CPs from it!

Control points

When dispatching an effect from the server you can define the location of control points 0 (with vecOrigin) and 1 (with vecStart).

On the client, you can configure the location, rotation and parent entity of any CP 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 a 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. To do: Global or only on current entity?
ParticleProp()->StopParticlesNamed( const char* )
Stops all effects with the given system name. To do: Global or only on current entity?
CNewParticleEffect::StopEmission( bool bInfiniteOnly, bool bRemoveAllParticles, bool bWakeOnStop)
Stops the current particle system, without removing it. To do: 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.