Particle arguments

A particle argument suggesting a list of Minecraft particle effects

The ParticleArgument class represents Minecraft particles. This is casted to the CommandAPI's ParticleData class.

The ParticleData class

The ParticleData class is a record that contains two values:

  • Particle particle, which is the Bukkit enum Particle representation of what particle was provided
  • T data, which represents any additional particle data which was provided.
public record ParticleData<T>(Particle particle, T data);

The T data can be used in Bukkit's World.spawnParticle(Particle particle, Location location, int count, T data) method.

Particle data

The particle argument requires additional data for a particle depending on what the particle is. Information about this can be found on the Argument types page on the MinecraftWiki. The following particles have additional data required to display them:

Bukkit ParticleArguments
BLOCK_CRACKblock block_id
block block_id[block_state=value]
BLOCK_MARKERblock_marker block_id
block_marker block_id[block_state=value]
FALLING_DUSTfalling_dust block_id
falling_dust block_id[block_state=value]
REDSTONEdust red green blue size
DUST_COLOR_TRANSITIONdust_color_transition red1 green1 blue1 size red2 green2 blue2
ITEM_CRACKitem item_id
item item_id{NBT}
VIBRATIONvibration x y z ticks

ParticleArgument examples

Because certain particles (in the table above) require additional data, it is no longer recommended to spawn a particle without its corresponding data. This can result in particles not showing due to missing requirements.

Example - Show particles at a player's location (without data)

Say we wanted to have a command that displayed particles at a player's location. We will use the following command syntax:

/showparticle <particle>

With this, we can simply spawn the particle using the World.spawnParticle(Particle, Location, int) method:

new CommandAPICommand("showparticle")
    .withArguments(new ParticleArgument("particle"))
    .executesPlayer((player, args) -> {
        ParticleData<?> particleData = (ParticleData<?>) args[0];
        player.getWorld().spawnParticle(particleData.particle(), player.getLocation(), 1);
    })
    .register();

CommandAPICommand("showparticle")
    .withArguments(ParticleArgument("particle"))
    .executesPlayer(PlayerCommandExecutor { player, args ->
        val particleData = args[0] as ParticleData<Any>
        player.world.spawnParticle(particleData.particle(), player.location, 1)
    })
    .register()

Running this can result in errors due to missing requirements. If you provide a particle that has additional requirements, Bukkit will throw an error and the particle will not be displayed. Instead, the example below should be used.

Example - Show particles at a player's location (with data)

We can fix the issues with the example above by providing the data of the argument using the ParticleData record:

/showparticle <particle>

In this case, we'll use the World.spawnParticle(Particle particle, Location location, int count, T data) method which accepts some particle data:

new CommandAPICommand("showparticle")
    .withArguments(new ParticleArgument("particle"))
    .executesPlayer((player, args) -> {
        ParticleData<?> particleData = (ParticleData<?>) args[0];
        player.getWorld().spawnParticle(particleData.particle(), player.getLocation(), 1, particleData.data());
    })
    .register();

CommandAPICommand("showparticle")
    .withArguments(ParticleArgument("particle"))
    .executesPlayer(PlayerCommandExecutor { player, args ->
        val particleData = args[0] as ParticleData<Any>
        player.world.spawnParticle(particleData.particle(), player.location, 1, particleData.data())
    })
    .register()

This can be used with commands such as:

/showparticle minecraft:dust_color_transition 0 0 0 20 1 0 0
/showparticle minecraft:block_marker diamond_block