Blitz3D+ Command Reference

CreateParticleEmitter ( [maximum][,parent] )

Parameters

maximum (optional) - most particles that may be alive at once; 256 (default), clamped to 1-16383

parent (optional) - parent entity for the emitter; 0 for none (default)

Description

Creates a CPU-simulated particle emitter entity. For GPU simulation use CreateGPUParticleEmitter.

This is the constructor for the CPU particle backend. It hands back a normal entity handle, so all the usual entity commands work on it: PositionEntity to place your campfire, EntityParent or the parent argument to bolt a jet exhaust onto a ship, EntityTexture to give the particles a sprite, EntityBlend for additive glow, EntityOrder to force a HUD effect in front, and FreeEntity to throw the whole thing away.

A fresh emitter is already running: it emits 20 particles per second, each living one second, moving up at 1 unit per second from a single point, fading from opaque white to transparent white at a size of 0.1. That is deliberately dull, so the usual next step is ParticlePreset to drop in a ready-made fire, smoke, rain, sparks, magic or dust effect, then tweak the parts you care about.

The maximum decides how big the emitter's vertex buffer is. Once that many particles are alive, new ones are simply not spawned until old ones die, so pick a number that covers your busiest moment - a rough guide is emission rate multiplied by the longest lifetime. It is clamped to 1-16383, and in mesh render mode the real ceiling drops further because one particle costs as many vertices as the mesh has (the buffer holds at most 65535 vertices).

Gotcha: particles are simulated by UpdateWorld, not by RenderWorld. If your main loop only renders, the emitter will sit there empty. The default UpdateWorld tick of 1 advances the simulation by one 60 Hz step, so all the per-second settings assume you call UpdateWorld about 60 times a second.

CopyEntity works on an emitter and copies every setting, but not the particles that are currently alive - the copy starts empty and with the default random seed.

For the full story, see the Particles guide.

Requires Extended mode.

See also: ParticlePreset, ParticleMax, ParticleEmissionRate, EmitParticles, CountParticles.

Example

; CreateParticleEmitter 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

; Build a campfire emitter with the chosen particle maximum
max_particles=500
emitter=CreateParticleEmitter(max_particles)
PositionEntity emitter,0,0.2,0
ParticlePreset emitter,1

While Not KeyDown(1)

    ; Keys 1-3 recreate the emitter with a different maximum
    new_max=0
    If KeyHit(2) Then new_max=50
    If KeyHit(3) Then new_max=500
    If KeyHit(4) Then new_max=2000
    If new_max>0
        FreeEntity emitter
        ; The emitter is an entity, so the usual entity commands work on it
        emitter=CreateParticleEmitter(new_max)
        PositionEntity emitter,0,0.2,0
        ParticlePreset emitter,1
        max_particles=new_max
    EndIf

    ; 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   1/2/3: recreate with max 50/500/2000   Esc: exit"
    Text 0,20,"CreateParticleEmitter("+max_particles+")"
    Text 0,40,"Live particles: "+CountParticles(emitter)+" (capped at the maximum)"

    Flip

Wend

End

Index