Particles API

Spawn, control, and replace prepared particle effects.

Use api.particles() to create particle effects prepared for the current scene.

ParticlesAPI particles = api.particles();

Spawn a persistent effect

spawn(...) creates and starts a looping particle entity that remains available for later control:

ParticleRef smoke = api.particles().spawn("particles/smoke.p", 120f, 64f)
        .scale(1.5f);

smoke.pause();
smoke.play();
smoke.stop();
smoke.restart();

The .p suffix is optional, so particles/smoke resolves to the same effect. The coordinates are the emitter’s world position. Moving its transform moves the effect; transform origin values are not an additional particle offset.

Use loop(false) for a persistent non-looping emitter. It remains an entity when emission completes or stops, so it can be restarted. Call remove() when you no longer need it.

ParticleRef also exposes entity(), entityId(), transform(), and particles(). Use its EntityRef when another Runtime API needs the spawned entity.

Spawn a one-shot effect

api.particles().oneshot("particles/dust.p", 120f, 64f);

oneshot(...) starts a non-looping effect and removes its entity when the effect completes. Use it for impacts, dust puffs, and other fire-and-forget feedback.

Control an existing emitter

Use the particle facade from an EntityRef:

EntityRef torch = api.entities().requireName("Torch");

torch.particles()
        .setLooping(true)
        .restart();

The facade supports play(), pause(), resume(), restart(), stop(), setLooping(...), and setAutoStart(...). Use isPaused() and isLooping() to inspect its current controls.

See Entity Facades for the shared entity-facade model.

To replace an emitter’s effect:

torch.particles().setEffect("particles/blue-flame.p", "main");

The path and atlas tag must be non-blank, and the replacement effect must already be prepared. A failed replacement leaves the previous effect unchanged.

Prepare effects before gameplay

Particle calls never load an undeclared effect during gameplay. Add every effect used from code to Runtime Availability before loading the scene.

If an effect was not prepared before the scene reached READY, spawn(...), oneshot(...), or setEffect(...) throws IllegalStateException.