Particle data (1.16.5 - 1.20.4)

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 ParticleMinecraft particleArguments
BLOCK_CRACKblockblock block_id

block block_id[block_state=value]
BLOCK_MARKERblock_markerblock_marker block_id

block_marker block_id[block_state=value]
REDSTONEdustdust red green blue size
DUST_COLOR_TRANSITIONdust_color_transitiondust_color_transition red1 green1 blue1 size red2 green2 blue2
FALLING_DUSTfalling_dustfalling_dust block_id

falling_dust block_id[block_state=value]
ITEM_CRACKitemitem item_id

item item_id{NBT}
SCULK_CHARGEsculk_chargesculk_charge angle
SHRIEKshriekshriek delay
VIBRATIONvibrationvibration x y z ticks

ParticleArgument examples

Because certain particles (in the table above) require additional data, it is not 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.get("particle");
        player.getWorld().spawnParticle(particleData.particle(), player.getLocation(), 1);
    })
    .register();

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

commandAPICommand("showparticle") {
    particleArgument("particle")
    playerExecutor { player, args ->
        val particleData = args["particle"] as ParticleData<Any>
        player.world.spawnParticle(particleData.particle(), player.location, 1)
    }
}

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.get("particle");
        player.getWorld().spawnParticle(particleData.particle(), player.getLocation(), 1, particleData.data());
    })
    .register();

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

commandAPICommand("showparticle") {
    particleArgument("particle")
    playerExecutor { player, args ->
        val particleData = args["particle"] as ParticleData<Any>
        player.world.spawnParticle(particleData.particle(), player.location, 1, particleData.data())
    }
}

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

Particle data implementation notes

The vibration particle will return a particle data of the Bukkit Vibration class. In the Vibration class, you can access the destination location using the Vibration.getDestination() method, which returns a Vibration.Destination instance. The CommandAPI will always return a Vibration.Destination.BlockDestination instance, and will never return a Vibration.Destination.EntityDestination instance. An example of accessing the location can be found below:

ParticleData<Vibration> particleData; // The particle data you get from your argument
Location destination = ((BlockDestination) particleData.data().getDestination()).getLocation();