Guides VFX & Particles Particles Particle Profiles

VFX & Particles Particles 2 min read Updated Aug 2026

Particle Profiles

A particle profile is a reusable `.particle.json` asset. It stores the same module data that a `ParticleSystem` component can store inline, but outside the scene.

Profiles let you author an effect once and reuse it across objects, prefabs, scenes, and scripts.

Create A Profile

  1. Open the Asset Browser.
  2. Right-click the target folder.
  3. Open Create.
  4. Open Particle Profile.
  5. Choose 2D or 3D.
  6. Name the asset.

The editor writes the particle data when values are saved. You should not need to hand-author the JSON for normal projects.

Assign A Profile

Select a GameObject with a ParticleSystem component, then set the component's Profile field to a .particle.json asset.

When a profile is assigned, the component reads module settings from that profile. Scene-level fields can still override values that the component stores inline, but the cleanest workflow is:

  • put shared effect behavior in the profile
  • keep scene-specific transform placement on the GameObject
  • use PHP only for playback and simple runtime swaps

When To Use Inline Settings

Inline settings are fine for one-off effects. Use them when the effect belongs only to one scene or one object.

Examples:

  • a one-time cutscene sparkle
  • a temporary prototype effect
  • an object-specific effect that will not become a prefab

When To Use Profiles

Use profiles for authored effects you want to keep stable and reusable.

Examples:

  • LandingDust.particle.json
  • TorchSmoke.particle.json
  • PickupSparkle.particle.json
  • RainLight.particle.json
  • ImpactSparks3D.particle.json

Profiles become especially valuable when you have prefabs. A torch prefab can reference TorchSmoke.particle.json, and all torch instances will use the same smoke behavior.

Load Profiles From PHP

use Lenga\Engine\Core\ParticleSystem;

$particles = $this->getComponent(ParticleSystem::class);

if ($particles !== null) {
    $particles->loadProfile('Assets/Particles/TorchSmoke.particle.json');
    $particles->play();
}

Use loadProfile() when the same object can change effect style at runtime. For example, a spell object might switch from an idle aura profile to a burst profile.

Profile Naming

Name profiles after the effect, not the object that happens to use it.

Prefer:

  • LandingDust.particle.json
  • SmallFire.particle.json
  • BlueMagicBurst.particle.json

Avoid:

  • PlayerParticles.particle.json
  • EnemyThing.particle.json
  • NewParticleProfile2D.particle.json

Effect names make profiles easier to reuse and easier to search in a large project.

Missing Or Broken Profiles

If a profile path is missing, Lenga keeps the profilePath value so the reference can be repaired later. The system falls back to defaults or inline data where available.

When a profile does not appear to apply:

  • confirm the file exists under the project
  • confirm the path is project-relative
  • confirm the file root key is particleSystem
  • confirm the profile dimension matches the scene workflow you expect
  • save and reload the scene if you are checking serialized data