Blitz3D+ Command Reference

CountParticles ( emitter )

Parameters

emitter - CPU or GPU particle emitter entity

Description

Returns the number of particles currently alive in an emitter.

On GPU emitters this is an exact query at this point in the command stream. It submits pending operations and may wait for a counter readback, even without RenderWorld or Flip. Repeated queries at an unchanged sequence reuse their result. Use CountParticlesAsync in a HUD to avoid a GPU wait.

This is the live population, not a lifetime total: it rises as particles spawn and falls as they reach the end of their lifetime. Printing it in a debug overlay is the quickest way to see whether an effect is doing what you think it is.

It is mostly used for tuning. If the count sits pinned at the value you passed to ParticleMax, the emitter is saturated and particles are being dropped - raise the maximum, lower the emission rate, or shorten the lifetime. If the count settles well below the maximum you are paying for buffer space you never use.

It also makes a good "is this effect finished" test. After a one-shot burst you can wait for the count to reach 0 before freeing the emitter or moving on to the next stage of a cut scene.

Automatic emission and aging require UpdateWorld. Explicit bursts, clear and capacity changes can change the count even while paused or without an update.

Requires Extended mode.

See also: ParticleMax, ParticleTotalEmitted, ClearParticles, ParticleEmissionRate.

Example

; CountParticles 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 fiery fountain in the middle of the scene
emitter=CreateParticleEmitter(1000)
PositionEntity emitter,0,0.5,0
ParticleLifetime emitter,1.5,2.5
ParticleVelocity emitter,0,4,0,0.6,0.5,0.6
ParticleGravity emitter,0,-4,0
ParticleColor emitter,255,220,120,1,255,80,0,0
ParticleSize emitter,0.12,0.03,0.2
EntityBlend emitter,3

rate=100

While Not KeyDown(1)

    ; [ / ] change the emission rate, Space fires a burst
    If KeyDown(26) And rate>0 Then rate=rate-2
    If KeyDown(27) And rate<400 Then rate=rate+2
    ParticleEmissionRate emitter,rate
    If KeyHit(57) Then EmitParticles emitter,200

    ; 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   [ / ] : emission rate   Space: burst   Esc: exit"
    ; CountParticles reports how many particles are alive right now
    Text 0,20,"CountParticles(emitter) = "+CountParticles(emitter)
    Text 0,40,"Emission rate: "+rate+" per second"

    Flip

Wend

End

Index