Blitz3D+ Command Reference

ParticleCollisionCount ( emitter )

Parameters

emitter - CPU or GPU particle emitter entity

Description

Returns how many particle collisions have happened since the emitter was last cleared.

GPU emitters do not collide and return 0 without a GPU readback.

The counter only moves when collision is switched on with ParticleCollision. Every time a particle's swept move is blocked by the Box3D world it bounces and this total goes up by one, so a single long-lived spark skidding along the floor can contribute many hits.

In a game this is most useful as a cheap "did it land" signal. Watch the count while a burst of sparks falls: the frame where it starts climbing is the frame the debris reached the ground, which is a decent cue for a dust puff, a sound effect, or a scorch decal - without writing any per-particle code.

It is also the fastest way to check that collision is really configured. If the count never moves, the usual causes are a physics world handle of 0, a collision radius that is too small for the particle speed, or geometry that has no Box3D body in that world.

Gotcha: ClearParticles resets this counter to 0 (and so does loading a ParticlePreset, which clears the emitter and switches collision off). That makes ClearParticles a convenient way to start a fresh measurement.

Requires Extended mode.

See also: ParticleCollision, ClearParticles, CountParticles, CreatePhysicsWorld.

Example

; ParticleCollisionCount Example
; ------------------------------
; Requires Extended mode.

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

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

; A Box3D physics world with a static slab for particles to bounce on
world=CreatePhysicsWorld()
slab=CreateCube()
ScaleEntity slab,3,0.25,3
PositionEntity slab,0,0.25,0
EntityColor slab,55,60,72
slab_body=CreatePhysicsBody(world,slab,0)
slab_shape=PhysicsBodyBox(slab_body,6,0.5,6,0)

; Sparks raining down and bouncing off the slab
emitter=CreateParticleEmitter(600)
PositionEntity emitter,0,3.5,0
ParticlePreset emitter,4
ParticleEmissionRate emitter,120
ParticleGravity emitter,0,-6,0
ParticleCollision emitter,world,0.04,0.65,0.15

While Not KeyDown(1)

    ; Space fires an extra burst, R clears particles and resets the count
    If KeyHit(57) Then EmitParticles emitter,150
    If KeyHit(19) 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: burst   R: reset count   Esc: exit"
    ; ParticleCollisionCount totals hits since particles were last cleared
    Text 0,20,"ParticleCollisionCount(emitter) = "+ParticleCollisionCount(emitter)
    Text 0,40,"Live particles: "+CountParticles(emitter)

    Flip

Wend

FreePhysicsWorld world
End

Index