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.

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 Particle	Minecraft particle	Arguments
`BLOCK_CRACK`	`block`	`block block_id` `block block_id[block_state=value]`
`BLOCK_MARKER`	`block_marker`	`block_marker block_id` `block_marker block_id[block_state=value]`
`REDSTONE`	`dust`	`dust red green blue size`
`DUST_COLOR_TRANSITION`	`dust_color_transition`	`dust_color_transition red1 green1 blue1 size red2 green2 blue2`
`FALLING_DUST`	`falling_dust`	`falling_dust block_id` `falling_dust block_id[block_state=value]`
`ITEM_CRACK`	`item`	`item item_id` `item item_id{NBT}`
`SCULK_CHARGE`	`sculk_charge`	`sculk_charge angle`
`SHRIEK`	`shriek`	`shriek delay`
`VIBRATION`	`vibration`	`vibration 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.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();

CommandAPI Documentation v9.3.0