ParticleSystem
Namespace:
namespace Lenga\Engine\Core;
final class ParticleSystem extends ComponentEach ParticleSystem controls one native 2D or 3D particle emitter attached to a GameObject. A GameObject may have multiple ParticleSystem components for layered effects.
Author detailed modules, curves, gradients, bursts, renderer settings, and reusable .particle.json profiles in the editor. Use PHP for playback, burst emission, profile swaps, texture swaps, and simple runtime tuning.
Sub Emitters are authored in the editor or in particle profiles. At runtime,
Lenga currently supports Birth and Death burst slots that emit from their target
ParticleSystem automatically, including per-slot Emit Probability; there is no
separate PHP method to trigger or configure a sub-emitter slot yet. Unity-style
Birth-over-lifetime, Manual, Collision, Trigger, and Inherit behavior is planned
but should not be treated as available runtime API.
For authoring workflows, start with Particle Systems. For scripted control patterns, see Script Particle Systems.
When an editor-authored field uses a curve, gradient, or random range, the simple PHP properties return a deterministic preview value. Use profiles for detailed authoring and PHP setters for straightforward runtime tuning.
Properties
public bool $isPlaying { get; }
public int $aliveParticleCount { get; }
public string $dimension { get; set; }
public string $simulationSpace { get; set; }
public string $customSimulationSpaceId { get; set; }
public string $deltaTime { get; set; }
public string $scalingMode { get; set; }
public string $emitterVelocityMode { get; set; }
public string $stopAction { get; set; }
public string $ringBufferMode { get; set; }
public float $ringBufferLoopRangeMin { get; set; }
public float $ringBufferLoopRangeMax { get; set; }
public string $sortingLayer { get; set; }
public int $orderInLayer { get; set; }
public string $texturePath { get; }
public string $profilePath { get; }
public float $emissionRate { get; set; }
public float $lifetime { get; set; }
public float $startSpeed { get; set; }
public float $startSize { get; set; }
public float $endSize { get; set; }
public string $shapeType { get; set; }
public Color $startColor { get; set; }
public Color $endColor { get; set; }
public float $simulationTimeMs { get; }
public int $renderSubmissions { get; }dimension is 2D or 3D. shapeType accepts values such as Point, Line, Circle, Rectangle, Cone2D, Sphere, Hemisphere, Box, and Cone3D.
simulationSpace is Local, World, or Custom (simulating in the
Transform of the scene object referenced by customSimulationSpaceId).
deltaTime is Scaled or Unscaled. scalingMode is Hierarchy,
Local, or Shape. emitterVelocityMode is Transform or Rigidbody.
stopAction is None, Disable, or Destroy and applies to the
GameObject once a stopped system has no live particles. ringBufferMode is
Disabled, PauseUntilReplaced, or LoopUntilReplaced with the loop range
expressed as normalized 0..1 lifetimes.
simulationTimeMs and renderSubmissions are read-only aggregate
profiling values; the bridge never exchanges per-particle data.
The properties sortingLayer, orderInLayer, texturePath, startColor, and endColor remain supported for existing scripts. Setting startColor or endColor from PHP writes a simple constant color setup; use the editor profile when an effect needs random colors or gradients.
Methods
play
public function play(): voidStarts the emitter.
pause
public function pause(): voidPauses simulation without clearing living particles.
stop
public function stop(bool $clear = false): voidStops emission. Pass true to clear living particles immediately.
restart
public function restart(bool $keepSeed = false): voidClears and starts the system. Pass true to keep the current deterministic seed sequence.
clear
public function clear(): voidRemoves all living particles.
simulate
public function simulate(float $seconds, bool $restart = false): voidAdvances the particle simulation manually. This is useful for warmup, scripted previews, and deterministic setup.
emit
public function emit(int $count, array $options = []): voidCreates a burst immediately. The optional $options parameter is reserved for future per-burst overrides.
getCollisionEvents
public function getCollisionEvents(): arrayReturns this frame's batched particle collision events. Recording requires
the Collision module's Send Messages option (or a Collision sub-emitter
slot). Each event carries particleId, point, normal, velocity
(approach velocity), approachSpeed, colliderId, and colliderName. The
buffer is bounded per frame and rebuilt every update, so poll once per
update loop.
getTriggerEvents
public function getTriggerEvents(): arrayReturns this frame's batched trigger events for conditions whose action is
Callback. Each event carries particleId, position, velocity,
condition (Inside, Outside, Enter, or Exit), and colliderMask
(bits into the Trigger module's collider list).
triggerSubEmitter
public function triggerSubEmitter(int $slotIndex = -1): voidFires the system's Manual sub-emitter slots once for every live particle,
spawning each slot's emit count into its target system with the slot's
inheritance flags and emit probability applied. Pass a slot index to fire one
slot, or -1 to fire every Manual slot. Slots with other event types are
ignored.
loadTexture
public function loadTexture(string $texturePath): boolLoads a particle texture from a project-relative path.
loadProfile
public function loadProfile(string $profilePath): boolLoads a reusable .particle.json profile from a project-relative path.
getStartColor
public function getStartColor(): arrayReturns byte-channel RGBA values for the particle start color.
setStartColor
public function setStartColor(Color|array|int $red, ?int $green = null, ?int $blue = null, int $alpha = 255): voidSets the color used when particles spawn. Pass a Color, an RGBA array, or individual byte-channel values.
getEndColor
public function getEndColor(): arrayReturns byte-channel RGBA values for the particle end color.
setEndColor
public function setEndColor(Color|array|int $red, ?int $green = null, ?int $blue = null, int $alpha = 255): voidSets the color particles blend toward over their lifetime.
getState
public function getState(): arrayReturns particle state for debugging overlays, runtime UI, or advanced tools. Common keys include isPlaying, aliveParticleCount, dimension, maxParticles, emissionRate, lifetime, startSpeed, startSize, startRotation, flipRotation, texturePath, profilePath, shapeType, shapeRadius, shapeRadiusThickness, shapeArc, shapeArcMode, shapeEmitFrom, shapeAlignToDirection, renderMode, sortingLayer, and orderInLayer.
renderMode reports the editor-authored renderer mode, such as Billboard, StretchedBillboard, HorizontalBillboard, VerticalBillboard, or Mesh. Author detailed renderer settings in the editor or in a particle profile; PHP is best used for playback, bursts, profile swaps, and simple runtime tuning.
Example
use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\ParticleSystem;
final class LandingDust extends Behaviour
{
private ?ParticleSystem $dust = null;
public function start(): void
{
$this->dust = $this->getComponent(ParticleSystem::class);
$this->dust?->loadProfile('Assets/Particles/LandingDust.particle.json');
}
public function onLanded(): void
{
$this->dust?->restart(true);
$this->dust?->emit(16);
}
}