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 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 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();