Blitz3D+ Command Reference

ParticleAttractor emitter,x#,y#,z#,strength#,minimum_distance#

Parameters

emitter - CPU or GPU particle emitter entity

x# - attractor position on the x axis, in simulation space

y# - attractor position on the y axis

z# - attractor position on the z axis

strength# - pull towards the point; negative values push particles away

minimum_distance# - distance floor used by the falloff, which stops the pull becoming enormous close in; values below 0.001 are raised to 0.001

Description

Pulls every live particle towards a point in space.

The attractor gives you swirling, gathering effects without writing any per-particle code: sparkles spiralling into a collected pickup, souls being sucked into a portal, embers curling towards a chimney, or debris being drawn into a black hole. A negative strength turns it into a repulsor, useful for a shockwave that blows dust outwards.

The pull follows an inverse-square falloff, so it is weak far away and much stronger close in. The minimum distance is what keeps that behaving: it acts as a floor on the distance used in the falloff, so particles that pass right through the attractor point are not flung away at absurd speed. Raise it for a soft, wide pull; lower it for a sharp, violent one.

The position is given in the emitter's simulation space, which is world space by default. If you switch to local-space particles with ParticleSpace, the coordinates become emitter-relative, so an attractor at 0,0,0 sits on the emitter itself and travels with it.

Gotcha: an emitter has one attractor. Calling ParticleAttractor again moves it rather than adding a second, and there is no fade-out - the pull is on until you call ClearParticleAttractor. Loading a ParticlePreset also clears it.

Requires Extended mode.

See also: ClearParticleAttractor, ParticleGravity, ParticleDrag, ParticleSpace, ParticleVelocity.

Example

; ParticleAttractor 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 magic orb that circles the scene, dragging sparkles with it
orb=CreateSphere()
ScaleEntity orb,0.2,0.2,0.2
EntityColor orb,120,200,255

; Sparkles rising gently from the ground
emitter=CreateParticleEmitter(800)
PositionEntity emitter,0,0.2,0
ParticleEmitterShape emitter,1,5,0.1,5
ParticleEmissionRate emitter,150
ParticleLifetime emitter,2,3
ParticleVelocity emitter,0,0.8,0,0.2,0.2,0.2
ParticleColor emitter,120,200,255,1,255,255,255,0
ParticleSize emitter,0.08,0.02,0.3
EntityBlend emitter,3

strength#=6
angle#=0

While Not KeyDown(1)

    ; [ / ] change the attractor strength
    If KeyDown(26) And strength>0 Then strength=strength-0.1
    If KeyDown(27) And strength<20 Then strength=strength+0.1

    ; Move the orb in a circle
    angle=angle+1
    orb_x#=Cos(angle)*2
    orb_z#=Sin(angle)*2
    PositionEntity orb,orb_x,2.5,orb_z

    ; The inverse-square attractor follows the orb every frame
    ParticleAttractor emitter,orb_x,2.5,orb_z,strength,0.3

    ; 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   [ / ] : attractor strength   Esc: exit"
    Text 0,20,"ParticleAttractor emitter,x,2.5,z,"+strength+",0.3"

    Flip

Wend

End

Index