Blitz3D+ Command Reference

ClearParticles emitter

Parameters

emitter - CPU or GPU particle emitter entity

Description

Removes every live particle from an emitter.

Particles vanish instantly rather than fading out, which is exactly what you want when the world underneath them changes: teleporting the player, restarting a level, respawning a vehicle, or cutting to a new camera. Without it, the smoke from the last scene drifts into the new one.

The emitter itself keeps running. All of its settings survive, and if ParticleEmissionRate is non-zero it will start filling up again on the next UpdateWorld. To stop the flow as well, pause the emitter with PauseParticles or set the rate to 0 before clearing.

Clearing also resets the fractional emission remainder and the collision counter, so ParticleCollisionCount starts again from 0. That makes it a handy "start measuring now" marker when you are tuning a collision effect.

Gotcha: the lifetime total reported by ParticleTotalEmitted is not reset - it keeps counting for the life of the emitter. Changing simulation space with ParticleSpace and loading a ParticlePreset both clear the emitter for you as a side effect.

Requires Extended mode.

See also: CountParticles, PauseParticles, ParticleCollisionCount, ParticleTotalEmitted.

Example

; ClearParticles Example
; ----------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,2,-6
CameraClsColor camera,8,12,24

floor=CreatePlane()
EntityColor floor,30,34,44

; A chimney stack that puffs out smoke
chimney=CreateCylinder()
ScaleEntity chimney,0.3,1,0.3
PositionEntity chimney,0,1,0
EntityColor chimney,90,70,60

; Smoke rising from the chimney top
emitter=CreateParticleEmitter(800)
PositionEntity emitter,0,2,0
ParticleEmissionRate emitter,80
ParticleLifetime emitter,3,4
ParticleVelocity emitter,0,1,0,0.4,0.3,0.4
ParticleColor emitter,180,180,190,0.8,120,120,130,0
ParticleSize emitter,0.1,0.5,0.3
EntityBlend emitter,2

While Not KeyDown(1)

    ; Space removes every live smoke puff in one call
    If KeyHit(57) Then ClearParticles emitter

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    ; UpdateWorld also advances the particle simulation
    UpdateWorld
    RenderWorld

    Text 0,0,"Arrow keys: move camera   Space: ClearParticles   Esc: exit"
    Text 0,20,"Live particles: "+CountParticles(emitter)+" (watch the count drop to 0 on Space)"

    Flip

Wend

End

Index