Blitz3D+ Command Reference

EmitParticles emitter[,count]

Parameters

emitter - CPU or GPU particle emitter entity

count (optional) - number of particles to spawn right now; 1 (default)

Description

Spawns a burst of particles immediately.

This is the one-shot half of the particle system, and it is what you want for events rather than atmosphere: a bullet hitting a wall, a crate exploding into splinters, a pickup popping into sparkles, a footstep kicking up dust. Set ParticleEmissionRate to 0 so the emitter is idle, then call EmitParticles at the moment the event happens.

The new particles are created straight away using the emitter's current settings, so you can move the emitter to the impact point with PositionEntity and burst in the same frame. Each particle still picks its own random lifetime, velocity variation, size variation and starting rotation.

A burst is capped by the emitter budget: particles that would push the live count past ParticleMax are simply not created. Asking for 500 sparks from a 256 particle emitter quietly gives you the ones that fit, so size the emitter for your biggest burst.

Gotcha: a burst does not need UpdateWorld to appear, but it does need UpdateWorld to move - without it the particles will hang in the air at their spawn positions. A count of 0 or less does nothing.

Requires Extended mode.

See also: ParticleEmissionRate, ParticleMax, ClearParticles, ParticleTotalEmitted, ParticlePreset.

Example

; EmitParticles 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 powder keg that explodes into sparks on demand
keg=CreateCylinder()
ScaleEntity keg,0.4,0.5,0.4
PositionEntity keg,0,0.5,0
EntityColor keg,140,90,50

; Spark emitter with no continuous emission - bursts only
emitter=CreateParticleEmitter(1000)
PositionEntity emitter,0,1,0
ParticlePreset emitter,4
ParticleEmissionRate emitter,0

burst=100

While Not KeyDown(1)

    ; [ / ] change the burst size
    If KeyHit(26) And burst>25 Then burst=burst-25
    If KeyHit(27) And burst<500 Then burst=burst+25

    ; Space emits a one-off burst of sparks immediately
    If KeyHit(57) Then EmitParticles emitter,burst

    ; 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: explode   [ / ] : burst size   Esc: exit"
    Text 0,20,"EmitParticles emitter,"+burst
    Text 0,40,"Live particles: "+CountParticles(emitter)

    Flip

Wend

End

Index