Gorilla.Particle.Emitter Unit Reference

Particle emitter class and preset configuration for the particle system.

TParticlePreset

Randomization preset for single-value particle properties.

Inheritance: TPersistent → TParticlePreset

Unit: Gorilla.Particle.Emitter

Constructor

Create

constructor Create(const AMin, AMax: Integer; const ADivisor: Integer;
  const ANegative: Boolean);

Creates a preset with specified range and options.

Parameters:

  • AMin - Minimum value (before division)
  • AMax - Maximum value (before division)
  • ADivisor - Divisor for converting to float
  • ANegative - Allow negative values randomly

Properties

Min

property Min: Integer;

Minimum value before division.

Max

property Max: Integer;

Maximum value before division.

Divisor

property Divisor: Integer;

Divisor for float conversion. Result = Value / Divisor.

Negative

property Negative: Boolean;

If True, randomly returns positive or negative values.

Methods

Preset

procedure Preset(const AMin, AMax: Integer; const ADivisor: Integer;
  const ANegative: Boolean);

Reconfigure preset values.

GetRandomValue

function GetRandomValue(): Single; overload;
function GetRandomValue(const ANegative: Boolean): Single; overload;

Returns random value within configured range.

Usage:

var
  LPreset: TParticlePreset;
  LValue: Single;
begin
  LPreset := TParticlePreset.Create(10, 50, 10, False);
  LValue := LPreset.GetRandomValue();  // Returns 1.0 to 5.0
end;

GetMinValue / GetMaxValue

function GetMinValue(): Single;
function GetMaxValue(): Single;

Returns minimum/maximum value after division.

TParticleVectorPreset

Randomization preset for 3D vector particle properties.

Inheritance: TPersistent → TParticleVectorPreset

Constructor

Create

constructor Create(const AMin, AMax: Integer; const ADivisor: Integer;
  const ADirection: TPoint3D; const AAxis: TAllowedAxisSet = [axX, axY, axZ]);

Parameters:

  • AMin, AMax, ADivisor - Range values
  • ADirection - Direction multiplier
  • AAxis - Allowed axes ([axX, axY, axZ])

Properties

RangeX, RangeY, RangeZ

property RangeX: TParticlePreset;
property RangeY: TParticlePreset;
property RangeZ: TParticlePreset;

Individual axis presets.

Direction

property Direction: TPosition3D;

Direction multiplier applied to randomized vector.

Axis

property Axis: TAllowedAxisSet;

Axes allowed for randomization. Set of [axX, axY, axZ].

Methods

Preset

procedure Preset(const AMin, AMax: Integer; const ADivisor: Integer;
  const ADirection: TPoint3D; const AAxis: TAllowedAxisSet = [axX, axY, axZ]);

Reconfigure all axes with same values.

GetRandomValue

function GetRandomValue(): TPoint3D;

Returns random 3D vector.

Usage:

var
  LPreset: TParticleVectorPreset;
  LVec: TPoint3D;
begin
  // Upward velocity with horizontal spread
  LPreset := TParticleVectorPreset.Create(0, 100, 1000, Point3D(1, -10, 1));
  LVec := LPreset.GetRandomValue();
end;

TGorillaParticleEmitter

Base particle emitter class.

Inheritance: TGorillaMesh → TGorillaParticleEmitter

Platforms: All Gorilla platforms

Unit: Gorilla.Particle.Emitter

Constructor/Destructor

Create

constructor Create(AOwner: TComponent); override;

Creates particle emitter with default settings:

  • EmitTime: 16ms
  • EmitParticles: 10
  • MaxParticles: 1000
  • AutoEmit: True
  • Reuse: True

Destroy

destructor Destroy(); override;

Stops emitter, clears particles, and frees resources.

Properties

Active (Read-Only)

property Active: Boolean read GetActive;

Returns True if emitter timer/thread is running.

Time (Read-Only)

property Time: Single read GetTime;

Total time in seconds since Start() was called.

DeltaTime (Read-Only)

property DeltaTime: Single read GetDeltaTime;

Time in seconds since last update tick.

Particles (Read-Only)

property Particles: TGorillaParticleList read FParticles;

List of currently active particles.

MeshData (Read-Only)

property MeshData: TMeshData read GetMeshData;

Internal mesh data for particle vertices.

Thread (Read-Only)

property Thread: TThread read GetThread;

Async computation thread if Async = True, otherwise nil.

Emitted (Read-Only)

property Emitted: Integer read GetEmitted;

Number of currently active particles.

Configuration Properties

Camera

property Camera: TCamera;

Linked camera for particle sorting. Required for correct transparency.

Usage:

LEmitter.Camera := GorillaViewport1.Camera;

Async

property Async: Boolean;

Enable background thread processing. Recommended for > 5000 particles.

Default: False

EmitTime

property EmitTime: Integer;

Update interval in milliseconds.

Default: 16ms (~60 FPS)

Usage:

LEmitter.EmitTime := 33;  // 30 FPS

Reuse

property Reuse: Boolean;

Enable particle caching/reuse for better performance.

Default: True

AutoEmit

property AutoEmit: Boolean;

Automatically emit particles each interval.

Default: True

EmitParticles

property EmitParticles: Integer;

Number of particles to emit per interval (when AutoEmit = True).

Default: 10

MaxParticles

property MaxParticles: Integer;

Maximum number of simultaneously active particles.

Default: 1000

Note: Cannot reduce below current particle count.

MaxAutoEmitTime

property MaxAutoEmitTime: Integer;

Maximum auto-emit duration in milliseconds. 0 = infinite.

Default: 0 (infinite)

Usage:

// Emit for 5 seconds then stop
LEmitter.MaxAutoEmitTime := 5000;

AutoRotation

property AutoRotation: Single;

Automatic particle rotation per frame in shader.

Default: 0 (no rotation)

Usage:

LEmitter.AutoRotation := 0.5;  // Gentle rotation

ParticleFade

property ParticleFade: Single;

Fade particle edges to prevent clipping artifacts.

Default: 0 (no fading)

Usage:

LEmitter.ParticleFade := 2.5;

ShowBounds

property ShowBounds: Boolean;

Show/hide emitter bounding box (debug).

Default: False

Particle Property Presets

ParticlePosition

property ParticlePosition: TParticleVectorPreset;

Randomization preset for initial particle position.

ParticleVelocity

property ParticleVelocity: TParticleVectorPreset;

Randomization preset for particle velocity.

ParticleSize

property ParticleSize: TParticlePreset;

Randomization preset for particle size.

ParticleAngle

property ParticleAngle: TParticlePreset;

Randomization preset for particle rotation angle.

ParticleWeight

property ParticleWeight: TParticlePreset;

Randomization preset for particle weight.

ParticleGrowth

property ParticleGrowth: TParticlePreset;

Randomization preset for particle growth/shrinkage.

ParticleLifeTime

property ParticleLifeTime: TParticlePreset;

Randomization preset for particle lifetime.

Blending Properties

BlendFunc

property BlendFunc: TBlendEquationFunc;

Blending equation function.

Usage:

LEmitter.BlendFunc := TBlendEquationFunc.befAdd;

BlendSource

property BlendSource: TBlendFactor;

Source blending factor.

BlendDest

property BlendDest: TBlendFactor;

Destination blending factor.

AlphaBlendSource

property AlphaBlendSource: TBlendFactor;

Alpha channel source blending factor.

AlphaBlendDest

property AlphaBlendDest: TBlendFactor;

Alpha channel destination blending factor.

Influencers

Influencers

property Influencers: TGorillaParticleInfluencerList;

List of active influencers affecting particles.

Methods

Start

procedure Start(); virtual;

Start particle emitter timer/thread.

Triggers: OnStart event

Stop

procedure Stop(); virtual;

Stop particle emitter (particles remain visible).

Triggers: OnStop event

Clear

procedure Clear(); virtual;

Destroy all particles (active and cached).

ClearUnused

procedure ClearUnused(); virtual;

Free cached particles only.

EmitParticle

function EmitParticle(): PGorillaParticle; overload; virtual;
function EmitParticle(const APosition: TPoint3D): PGorillaParticle; overload; virtual;

Manually emit a single particle.

Returns: Pointer to emitted particle, or nil if MaxParticles reached

Usage:

// Random position
var LPart: PGorillaParticle;
begin
  LPart := LEmitter.EmitParticle();
end;

// Specific position (e.g., mouse click)
var LPos: TPoint3D;
begin
  LPos := ScreenToWorld(Mouse.X, Mouse.Y);
  LEmitter.EmitParticle(LPos);
end;

SortByEyeDistance

procedure SortByEyeDistance(const APosition: TPoint3D); virtual;

Sort particles by distance to camera for correct transparency.

Called automatically when Camera is assigned.

ForceUpdate

procedure ForceUpdate();

Force immediate particle update independent of timer.

AddInfluencer / RemoveInfluencer

procedure AddInfluencer(AInfl: TGorillaParticleInfluencer);
procedure RemoveInfluencer(AInfl: TGorillaParticleInfluencer);

Manage influencers.

ClearInfluencers

procedure ClearInfluencers();

Remove all influencers.

LoadTexture

procedure LoadTexture(const AFilename: String; const AParticleSize: Integer;
  const AIsSpriteSheet: Boolean; const ASpriteRows, ASpriteCols: Integer;
  const AFrameWidth: Integer = 0; const AFrameHeight: Integer = 0); virtual;

Helper to load particle texture and configure sprite sheet.

Parameters:

  • AFilename - Texture file path
  • AParticleSize - Default particle size
  • AIsSpriteSheet - True for animated sprites
  • ASpriteRows, ASpriteCols - Sprite sheet grid
  • AFrameWidth, AFrameHeight - Optional frame sizes

Usage:

LEmitter.LoadTexture('explosion.png', 64, True, 4, 4, 256, 256);

Events

OnStart

property OnStart: TNotifyEvent;

Fired when emitter starts.

OnStop

property OnStop: TNotifyEvent;

Fired when emitter stops.

OnProcess

property OnProcess: TOnAutoEmitProcess;

Fired during each auto-emit update.

TOnAutoEmitProcess = procedure(ASender: TObject;
  const AElapsedTime: Int64; const ADeltaTime: Double) of object;

OnEmitted

property OnEmitted: TOnParticleEmittedEvent;

Fired when particle is emitted (including reused particles).

TOnParticleEmittedEvent = procedure(ASender: TObject;
  const AParticle: PGorillaParticle) of object;

OnDispose

property OnDispose: TOnParticleNotifyEvent;

Fired before particle destruction.

TOnParticleNotifyEvent = procedure(ASender: TObject;
  const AParticle: PGorillaParticle) of object;

Examples

Basic Emitter

var
  LEmitter: TGorillaParticleEmitter;
begin
  LEmitter := TGorillaParticleEmitter.Create(Self);
  LEmitter.Parent := GorillaViewport1;
  LEmitter.Camera := GorillaViewport1.Camera;

  // Configure emission
  LEmitter.EmitParticles := 20;
  LEmitter.MaxParticles := 2000;
  LEmitter.AutoEmit := True;

  // Configure particles
  LEmitter.ParticleSize.Preset(16, 32, 1, False);
  LEmitter.ParticleLifeTime.Preset(2000, 5000, 1000, False);

  LEmitter.Start();
end;

One-Shot Effect

var
  LExplosion: TGorillaParticleEmitter;
begin
  LExplosion := TGorillaParticleEmitter.Create(Self);
  LExplosion.Parent := GorillaViewport1;
  LExplosion.Camera := Camera1;

  LExplosion.EmitParticles := 100;
  LExplosion.MaxAutoEmitTime := 100;  // Emit for 0.1 second
  LExplosion.ParticleLifeTime.Preset(500, 1500, 1000, False);

  LExplosion.Start();
end;

Interactive Emission

procedure TForm1.ViewportMouseDown(Sender: TObject; Button: TMouseButton;
  Shift: TShiftState; X, Y: Single);
var
  LPos: TPoint3D;
begin
  LPos := ScreenToWorld(X, Y);
  LEmitter.EmitParticle(LPos);
end;

See Also