ParticleSystem

Namespace:

namespace Lenga\Engine\Core;

final class ParticleSystem extends Component

ParticleSystem controls a native 2D particle emitter attached to a GameObject.

Use it when gameplay code needs to start, stop, clear, burst, or retarget a particle effect that was authored in the Inspector.

Getting the Component

The usual workflow is:

  1. Create or select a GameObject in the editor.
  2. Add Particle System from Add Component -> 2D -> Rendering.
  3. Add a Behaviour class to the same GameObject.
  4. In that script, call $this->getComponent(ParticleSystem::class).
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);
    }

    public function onLanded(): void
    {
        $this->dust?->emit(16);
        $this->dust?->play();
    }
}

Properties

isPlaying

public bool $isPlaying { get; }

Returns whether the emitter is currently playing.

aliveParticleCount

public int $aliveParticleCount { get; }

Returns how many particles are currently alive.

This is useful for debugging or for waiting until a one-shot effect has finished.

sortingLayer

public string $sortingLayer { get; set; }

Controls the 2D sorting layer used by the particles.

orderInLayer

public int $orderInLayer { get; set; }

Controls the draw order inside the selected sorting layer.

texturePath

public string $texturePath { get; }

Returns the currently assigned particle texture path.

If this is empty, the system draws simple circle particles.

Methods

play

public function play(): void

Starts the particle emitter.

stop

public function stop(bool $clear = false): void

Stops the particle emitter.

Pass true when you also want to remove existing particles immediately.

$particles->stop(true);

clear

public function clear(): void

Removes all currently alive particles.

emit

public function emit(int $count): void

Creates a burst of particles immediately.

$particles->emit(24);

loadTexture

public function loadTexture(string $texturePath): bool

Loads a new particle texture from a project-relative path.

Returns true when the texture was loaded successfully.

if (!$particles->loadTexture('Assets/Sprites/Effects/spark.png')) {
    Debug::warn('Could not load spark particle texture.');
}

getState

public function getState(): array

Returns the current native particle-system state as an array.

The returned array can include:

  • maxParticles
  • emissionRate
  • lifetime
  • startSpeed
  • startSize
  • gravity
  • emissionAngle
  • spreadAngle
  • looping
  • playOnAwake
  • isPlaying
  • aliveParticleCount
  • sortingLayer
  • orderInLayer
  • texturePath

Use getState() for diagnostics or UI display. Prefer the named properties and methods for normal gameplay code.

Runtime Workflow

The PHP surface exposes runtime control for play, stop, clear, burst emission, texture changes, and sorting.

Authoring settings such as emission rate, lifetime, speed, size, color, gravity, angle, and spread are edited in the Inspector. Use the Inspector to shape the emitter and use PHP to control playback, bursts, texture changes, and sorting during gameplay.

For the beginner workflow, see Add 2D Particle Effects.