This documents an old version of bs::framework. Click here to see the latest release.
Other particle system settings

We already mentioned ParticleSystemSettings when we have shown how to apply a Material to the particle system. In this manual we will go over the rest of the options provided by that object and show how they affect the particle system.

To recap, ParticleSystemSettings object can be assigned to a particle system by calling CParticleSystem::setSettings().

HParticleSystem particleSystem = ...;
// Set the material to be used by the particle system
ParticleSystemSettings psSettings;
psSettings.material = particleMaterial;

Duration and looping

Duration of the particle system controls how are time-based curves in various distributions evaluated. This includes all the distributions in ParticleEmitter but also other distributions that are evaluated based on system lifetime. When the particle system is first spawned its internal timer starts ticking and current time is incremented. This time is divided by the duration and then passed to relevant curves in [0, 1] range. Use ParticleSystemSettings::duration to set the duration in seconds.

Once the time passes the system duration the time will loop back to the start. If you prefer to instead clamp the time when the duration is reached, disable ParticleSystemSettings::isLooping.

ParticleSystemSettings psSettings;
psSettings.duration = 5.0f; // 5 seconds
psSettings.isLooping = true;

Simulation space

Simulation space controls in which space are particles spawned. It is set through ParticleSystemSettings::simulationSpace and can have two values:

  • ParticleSimulationSpace::Local - Particles are spawned in space local to the particle system. If you move the particle system all the particles will move with it. As an example imagine electrical sparks on a moving vehicle.
  • ParticleSimulationSpace::World - Particles are spawned in world space. If you move the particle system any existing particles will keep their original location while any newly spawned particles will spawn at the new location. As an example imagine a flamethrower as the player moves or rotates.
ParticleSystemSettings psSettings;
psSettings.simulationSpace = ParticleSimulationSpace::World;


This set of options allow you to modify how are particle billboards oriented. It is controlled through the ParticleSystemSettings::orientation field and can take on the following values:

  • ParticleOrientation::ViewPlane - Particles will be oriented towards the camera plane, so that their X & Y axes are parallel to the camera plane. All particles have the exact same orientation.
  • ParticleOrientation::ViewPosition - Achieves a similar effect as ParticleOrientation::ViewPlane, but orients towards the camera's position. Particles will have slightly different orientation depending on their position, but will still face the camera.
  • ParticleOrientation::Plane - Particles will always face a certain plane. The plane can be specified by setting ParticleSystemSettings::orientationPlane. This is particularily useful for 2D games.

You can also forbid particles to rotate around the Y axis by setting ParticleSystemSettings::orientationLockY. This can be useful for particles that must remain "upright", yet still face the camera. As an example imagine grass billboards.

ParticleSystemSettings psSettings;
psSettings.orientation = ParticleOrientation::ViewPosition;
psSettings.orientationLockY = true;

Render mode

This options allows to to choose should particles render as 2D billboards or as 3D meshes. It can be set through ParticleSystemSettings::renderMode and has two properties:

When rendering as a 3D mesh you will need to specify the mesh to use in the ParticleSystemSettings::mesh field. You might also want to use a shader that supports lighting, such as BuiltinShader::ParticleLitOpaque.

// Set up rendering of 3D particles
// Grab a mesh to use
HMesh mesh = gBuiltinResources().getMesh(BuiltinMesh::Sphere);
// Set up a material that supports lighting
HShader particleShader = gBuiltinResources().getBuiltinShader(BuiltinShader::ParticlesLitOpaque);
HMaterial particleMaterial = Material::create(particleShader);
particleMaterial->setTexture("gAlbedoTex", gBuiltinResources().getTexture(BuiltinTexture::White));
// Enable 3D particles
ParticleSystemSettings psSettings;
psSettings.material = particleMaterial;
psSettings.renderMode = ParticleRenderMode::Mesh;
psSettings.mesh = mesh;
3D particles


Certain particle shaders might require particles to be sorted in a particular order to work properly. You can control particle sorting through the ParticleSystemSettings::sortMode field. It has the following options:

Note that sorting is a potentially expensive process and should be disabled unless necessary.

ParticleSystemSettings psSettings;
psSettings.sortMode = ParticleSortMode::Distance;


Systems like visibility culling require the world bounds of the particle system to be calculated every frame. Bounds can be calculated automatically or bounds can be provided manually. Use ParticleSystemSettings::useAutomaticBounds to toggle automatic bound calculation.

When disabled you can provide custom bounds by setting ParticleSystemSettings::customBounds. User must ensure these bounds completely cover the potential particle system volume, otherwise is might get culled even when particles are still in view.

Using custom bounds saves the potentially expensive per-frame recalculation of bounds, but can decrease culling efficiency since the bounds might need to be larger than the actual effect at a particular frame.

ParticleSystemSettings psSettings;
psSettings.useAutomaticBounds = false;
psSettings.customBounds = AABox::UNIT_BOX;

Maximum particle count

ParticleSystemSettings::maxParticles can be used to limit the maximum number of particles. Once this number of reached no new particles will be spawned, until some old particles die and make room.

ParticleSystemSettings psSettings;
psSettings.maxParticles = 4000;


Emitters and most evolvers use random number generation when spawning/manipulating particles. Seed for those generators is generated automatically when the particle system is first spawned. This behaviour can be disabled by toggling ParticleSystemSettings::useAutomaticSeed. When automatic seed generation is disabled make sure to provide the custom seed in ParticleSystemSettings::manualSeed.

Using a custom seed ensures you can always achieve the same exact particle effect, while using an automatic seed will make your particle effect slightly different every time it is played.

ParticleSystemSettings psSettings;
psSettings.useAutomaticSeed = false;
psSettings.manualSeed = 123456;