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 floatANegative- 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 valuesADirection- Direction multiplierAAxis- 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 pathAParticleSize- Default particle sizeAIsSpriteSheet- True for animated spritesASpriteRows,ASpriteCols- Sprite sheet gridAFrameWidth,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
- Gorilla.Particle - Particle structure
- Gorilla.Particle.Influencer - Influencer classes
- Particle System User Guide