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("smoke", 120f, 64f)
        .scale(1.5f);

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

Use the particle effect name shown in Pixscape Studio. 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

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.

To replace an emitter’s effect:

torch.particles().setEffect("blue-flame", "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.

Code examples

Handle a projectile impact

Apply designer-authored damage, show prepared visual feedback, and remove the projectile.

void onProjectileImpact(EntityRef projectile, EntityRef target) {
    // Read damage authored on the projectile in Studio.
    int damage = projectile.properties().getInt("damage", 10);

    // Application gameplay owns health and damage rules.
    damageSystem.apply(target, damage);

    // The logical effect name resolves a prepared effect.
    api.particles().oneshot(
            "explosion",
            projectile.transform().x(),
            projectile.transform().y()
    );

    projectile.remove();
}

damageSystem is application code. The explosion effect must be prepared through Runtime Availability before the scene reaches READY.