Resource Comprehensive Particle Spawning Guide [1.13-1.18]

Discussion in 'Spigot Plugin Development' started by Esophose, Oct 13, 2018.

  1. Introduction
    I've noticed that there are quite a few threads popping up asking how to spawn particles with offsets, directional values, colors, or specific materials. I couldn't find any resources that explained exactly how to do all these things, so here we are. The following is a comprehensive guide on how to spawn particles in Spigot 1.13+.

    Spawning Methods
    There are two different ways you can spawn particles. You can use World#spawnParticle() which spawns particles for all players, or you can use Player#spawnParticle() which spawns particles for a single player. The methods you can use on both a World or a Player are as follows:
    Code (Java):
    spawnParticle(Particle particle, double x, double y, double z, int count)
    spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ)
    spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra)
    spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data)
    spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, T data)
    spawnParticle(Particle particle, double x, double y, double z, int count, T data)
    spawnParticle(Particle particle, Location location, int count)
    spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ)
    spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra)
    spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, T data)
    spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, T data)
    spawnParticle(Particle particle, Location location, int count, T data)
    There are two additional methods available specifically on the World that allow you to extend the viewing range of the particles:
    Code (Java):
    spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force)
    spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force)

    Method Parameters
    With all those parameters, some of the methods may look a little intimidating. Don't worry though, they're all pretty easy to understand when you break them out into their individual pieces.
    • Particle particle - The Particle type that you want to spawn, a full list is available Here
    • Location location - The Location where you want the particle to spawn
    • double x, y, z - The x, y, and z coordinates where you want the particle to spawn. This can be used instead of the Location parameter if you'd like. The world they spawn in will be either the World the method is called on, or the world that the Player is in
    • int count - The number of particles that you want to spawn
    • double offsetX, offsetY, offsetZ - How far away from the given Location (or x, y, z) you want the particles to be able to spawn
    • double extra - This controls some odd properties for some particles, sometimes it controls the speed, other times it controls how they're colored.
    • T data - The data that some particles require for spawning. This will be explained more in the section titled "Colored Particles" and the section titled "Material Particles"
    • boolean force - If true, players will be able to see particles from much further away than normal
    Directional Particles
    Some particle types can be spawned with special directional values rather than position offsets. The following particles are able to use directional values (from my personal experience, I tested all the particles and these were the ones that had their direction influenced):
    Code (Text):
    EXPLOSION_NORMAL
    FIREWORKS_SPARK
    WATER_BUBBLE
    WATER_WAKE
    CRIT
    CRIT_MAGIC
    SMOKE_NORMAL
    SMOKE_LARGE
    PORTAL
    ENCHANTMENT_TABLE
    FLAME
    CLOUD
    DRAGON_BREATH
    END_ROD
    DAMAGE_INDICATOR
    TOTEM
    SPIT
    SQUID_INK
    BUBBLE_POP
    BUBBLE_COLUMN_UP
    NAUTILUS
    CAMPFIRE_COZY_SMOKE
    CAMPFIRE_SIGNAL_SMOKE
    SOUL_FIRE_FLAME
    SOUL
    REVERSE_PORTAL
    SMALL_FLAME
    ELECTRIC_SPARK
    SCRAPE
    WAX_OFF
    WAX_ON
    To use the directional properties of these particles, simply set the count parameter to 0. This will then make the offsetX, offsetY, and offsetZ become directional parameters rather than offsets. To control the speed, the extra value can be used. Please note that you will only be able to spawn one particle at a time if you are going to use directional parameters.

    Colored Particles
    Some particles have the ability to be colored. I have to break this up into three sections because there are three different ways to color certain particles:
    Spawning REDSTONE particles is probably the easiest out of the bunch now that there is a DustOptions class. The DustOptions constructor takes an org.bukkit.Color, and a float. The Color is what color the particles will be, and the float is the size of the particle. This size option is new to 1.13. The normal size that you see REDSTONE particles at is just 1, but you could specify a different size if you desire. The following is an example of how to spawn 50 blueish-green REDSTONE particles with a size of 1:
    Code (Java):
    DustOptions dustOptions = new DustOptions(Color.fromRGB(0, 127, 255), 1.0F);
    player.spawnParticle(Particle.REDSTONE, player.getLocation(), 50, dustOptions);
    Spawning colored SPELL_MOB and SPELL_MOB_AMBIENT particles takes a little more work than spawning REDSTONE particles. First, the count parameter needs to be set to 0 if you want to get your exact color. Then offsetX, offsetY, and offsetZ will be used as your Red, Green, and Blue values respectively. These values must be between 0 and 1 in order to work properly. They should be in intervals of 1/255. This is where that extra parameter comes into play. If you set extra to any value other than 1, the color of the particles will be pretty much random, or completely black if you set it to 0. Here is some code you can use to spawn SPELL_MOB or SPELL_MOB_AMBIENT particles that are a blueish-green color:
    Code (Java):
    double red = 0 / 255D;
    double green = 127 / 255D;
    double blue = 255 / 255D;
    player.spawnParticle(Particle.SPELL_MOB, player.getLocation(), 0, red, green, blue, 1);
    Spawning NOTE particles is very similar to spawning SPELL_MOB particles. The difference is that there are only 24 color values to choose from. The offsetX value should be a number between 0 and 1 and be in intervals of 1/24. The offsetY and offsetZ values should always be 0. Make sure the count is set to 0 and the extra value is set to 1. Here is an example of how to spawn a red note:
    Code (Java):
    double note = 6 / 24D; // 6 is the value of the red note
    player.spawnParticle(Particle.NOTE, player.getLocation(), 0, note, 0, 0, 1);
    I'm not going to list what all 24 of the colors can be, you can experiment with those yourself to find them all.
    Spawning DUST_COLOR_TRANSITION particles is nearly identical to spawning REDSTONE particles, except instead of using DustOptions, you use DustTransition. The DustTransition constructor takes an org.bukkit.Color as the start color, an org.bukkit.Color as the end color, and a float as the size. The following is an example of how to spawn 50 red particles that fade to white with a size of 1:
    Code (Java):
    DustTransition dustTransition = new DustTransition(Color.fromRGB(255, 0, 0), Color.fromRGB(255, 255, 255), 1.0F);
    player.spawnParticle(Particle.DUST_COLOR_TRANSITION, player.getLocation(), 50, dustOptions);
    Note: Unfortunately, FIREWORKS_SPARK particles cannot be colored. The colors they get from fireworks are completely client-side, so we have no control over them. Particles spawned with colors will never match exactly what you set. The client applies a slight offset to each of the color values to give them some extra variance.

    Material Particles
    A few particles require that you pass either an ItemStack or BlockData into the T data parameter that changes their appearance. The following particles require this data:
    Code (Text):
    ITEM_CRACK (ItemStack.class)
    BLOCK_CRACK (BlockData.class)
    BLOCK_DUST (BlockData.class)
    FALLING_DUST (BlockData.class)
    The class in parenthesis next to the particle name is the Type of the T data parameter that you must pass in. The following are some examples of how you can spawn ITEM_CRACK and FALLING_DUST particles:
    Code (Java):
    ItemStack itemCrackData = new ItemStack(Material.STONE);
    player.spawnParticle(Particle.ITEM_CRACK, player.getLocation(), 10, itemCrackData);
     
    BlockData fallingDustData = Material.STONE.createBlockData();
    player.spawnParticle(Particle.FALLING_DUST, player.getLocation(), 10, fallingDustData);
     
    Note: The particles that require BlockData MUST be from Materials that have #isBlock() equal to true, otherwise you will get an IllegalArgumentException. ITEM_CRACK will accept both item and block ItemStacks.

    Vibration Particles
    If you are going to be using VIBRATION particles, you should know a few things ahead of time. This particle type has a very specific use case, and that is sending the particle from one location to another. You should not use this particle type for anything else, as it looks terrible (though interesting) when used in excess. The location or x, y, and z coordinates for this particle type are entirely ignored and are instead provided through the Vibration data class. The Vibration data class takes 3 parameters: an origin Location, a Vibration.Destination as the destination, and an int duration in ticks. The duration determines how long it takes for the particle to travel from the origin to the destination.
    To spawn VIBRATION particles towards a Block, you want to use Vibration.Destination.BlockDestination as the destination type. This class takes either a Location or a Block as the constructor parameter. The follow code demonstrates how to send a vibration particle from a player to a block over a duration of 2 seconds.
    Code (Java):
    Vibration vibration = new Vibration(player.getLocation(), new Vibration.Destination.BlockDestination(block), 40);
    player.getWorld().spawnParticle(Particle.VIBRATION, player.getLocation(), 1, vibration);
    To spawn VIBRATION particles towards an Entity, you want to use Vibration.Destination.EntityDestination as the destination type. This class takes an Entity as the constructor parameter. The follow code demonstrates how to send a vibration particle from a player to an entity over a duration of 2 seconds.
    Code (Java):
    Vibration vibration = new Vibration(player.getLocation(), new Vibration.Destination.EntityDestination(entity), 40);
    player.getWorld().spawnParticle(Particle.VIBRATION, player.getLocation(), 1, vibration);
    Note: The origin Location of the VIBRATION particles will always be snapped to the closest block coordinate. It is near impossible to fine-tune the appearance of this particle type.


    Additional Notes
    • I found a bunch of this information just by looking at the Bukkit/Spigot documentation and source code. I highly recommend you check it out the docs and the source code.
    • If you want to spawn particles in certain shapes, I highly recommend looking at some of the resource threads posted by @finnbon
    • Did I miss something? See something wrong? Please let me know and I'll get it updated/fixed.
     
    #1 Esophose, Oct 13, 2018
    Last edited: Dec 9, 2021
    • Useful x 63
    • Like x 14
    • Winner x 6
    • Friendly x 5
    • Informative x 3
  2. Thanks for that shoutout man :p
     
    • Winner Winner x 5
  3. Thank you for this tutorial,
    I know this is an old thread but many people still using it (I think)
    That's why I would like to report you this part of code:
    Code (Text):

    DustOptions dustOptions = new DustOptions(Color.fromRGB(0, 127, 255), 1);
    player.spawnParticle(Particle.REDSTONE, player.getLocation(), 50, dustOptions);
    I thought my code was wrong because it spawned 10K of particles for a simple circle,
    player.spawnParticle(Particle.REDSTONE, player.getLocation(), 50, dustOptions);
     
    • Agree Agree x 4
  4. This is very good, thanks, man.

    I would like to ask you a question. I want to spawn particles nicely around a block (head), so as the location I select the block location and x, y & z offset set to 1? And what numbers should I choose as a count?
    I imagine it like flames around spawner.
     
    • Like Like x 1
  5. Thanks you so much <3
     
    • Friendly Friendly x 2
  6. I also recommend XParticle for cross-version particle enum compatibility :)
     
  7. On version 1.15.2, block_dust seems to throw an illegal argument exception. Even using your code examples it says it expects MaterialData but got CraftBlockData. Any idea why this could be?
     
  8. I am using BlockData in my plugin PlayerParticles and it works fine. You can look at the source for the Particle class and even see what types of data are required: https://hub.spigotmc.org/stash/proj...wse/src/main/java/org/bukkit/Particle.java#47

    It has used BlockData since 1.13, and used MaterialData before that. Are you sure that issue is occurring on a 1.15 server?
     
  9. Hello, sorry for necro, can you help me with block.getLocation, so now it spawns particles in the corner of block, how i can center it?
    I guess offset select random direction?

    UPD: solved with getX/Z + 0.5
     
    #9 FrostExZo, May 1, 2021
    Last edited: May 1, 2021
  10. add 0.5 to x,y and z
     
  11. Just adding 0.5 to the xyz of the block will center it.
    Code (Text):
    block.getLocation().clone().add(0.5, 0.5, 0.5)
    Edit: sniped :(
     
  12. Updated to include new 1.17 particles and data types.
     
    • Friendly Friendly x 1
  13. Great resource, very clear for anybody who wants to know more about particles, especially about 1.17 particles.

    If you want to add even more details, I have some ideas if you want :

    1. You can maybe add informations about specific particles that react strangly while directionnal, like effect (SPELL), entity_effect (MOB_SPELL) and ambient_entity_effect (SPELL_MOB_AMBIENT). If we want to use colored mob spell particle in vanilla, we have to use directional particles : /particle entity_effect x y z <red> <green> <blue> <saturation 0 to 1> 0 <normal|force> <viewers>. Here the offset (so the velocity since it's directionnal with count=0) becomes color, the speed becomes the saturation and the count has to be to 0. It's the case for every three particles I listed. I have no idea why Mojang didn't add something like DustOptions to color those, but well... Obviously, to use those particles with specific colors with Bukkit, we just have to use same values.

    2. Additionally, I think some people knows approximately how /particle command works. In CraftBukkit, we can easily find the link between vanilla particle names and Bukkit particle names, so those people would understand Bukkit/Spigot particles better.
     
  14. The color oddities regarding the offsets is already mentioned under the Colored Particles > Spawning SPELL_MOB Particles section. I do think it would be a decent idea to document how the /particle commands works though, might add that in the future.
     
  15. Thanks for the 1.17 update :D
     
  16. Oh nevermind, didn't see the menu, I searched "mob_spell" not "spell_mob", sorry for that.
     
    • Friendly Friendly x 1
  17. hi
     
    • Optimistic Optimistic x 1
  18. I need help, how do i set the particle speed and to make it so it spawns everytime?
    upload_2021-12-9_1-54-41.png
     
  19. The particle speed is the value labeled extra. Not all particles can have a speed applied to them though.
     
  20. can the firework spark or the snowflake have speed, how do i know if it can have speed? also do i just do extra 1 or do i have to type something extra upload_2021-12-9_2-44-31.png