Bukkit/CraftBukkit — pull request #1334 by SpaceManiac (2014-02-06 03:56:09+00:00)
Title: [B+C] Adds methods for displaying particle effects. Adds BUKKIT-3792

**The Issue:**

There is no method to display specific particle effects to the users like there are to play individual sounds (Sound) or special effects (Effect).

**Justification for this PR:**

A wide variety particle effects are not currently possible to display to players, and it would be useful to be able to display them.

**PR Breakdown:**

A new Particle enum is added to Bukkit, containing the known valid particle effect types. Two showParticles methods each are added to Player and World, to show a particle effect to a single player or nearby players, with or without material data.

The reason for making Particle its own class separate from Effect is twofold. First, the kind of data you need to show a Particle is largely different from that of an Effect. Second, to be parallel to Sound, which is also separate. Sounds and Particles are two kinds of effect to play to the player. The Effect enum contains several special predefined (by Minecraft) combinations of sounds and/or particles.

While this PR *could* be considered complete, there are a few issues that should be addressed:

* How to document specific details about what each argument to showParticle does and to which particles (caveats, so on).
* Potentially adding range-limited methods (NMS's default limit is 16 blocks).
* Unit tests? Sound has no tests and Effect has a trivial, non-applicable test.
* Potentially adding a method which takes a string instead of Particle(+MaterialData), for the upcoming 1.8 particle command.
* Better name for showParticle? showParticles? showParticleEffect? I went with succintness to start.
* Maybe better validation of MaterialData passed (ITEM_BREAK expects item, other two expect block). No crashes involved, just particles looking silly.
* More descriptive commit message. The current one is just basic info, the real goods are in this PR description.

This is kind of a long list, I know, but I wanted to at least get this initial version up and in the pipeline.

**Testing Results and Materials:**

Testing plugin code: https://gist.github.com/SpaceManiac/8837964
Testing plugin download: http://wombat.platymuus.com/dl/ParticleTest.jar

How to use:
/particles list - displays Particle.values()
/particles all - shows all particle types in sequence to only you
/particles [name] - shows one particle type to all players
All particles are spawned above the player's head (use third person view)

**Relevant PRs:**

B-1025 - https://github.com/Bukkit/Bukkit/pull/1025 - Accompanying Bukkit PR

B-802 - https://github.com/Bukkit/Bukkit/pull/802 - Past effort to address this ticket
CB-1066 - https://github.com/Bukkit/CraftBukkit/pull/1066 - Past effort to address this ticket

**JIRA Ticket:**

BUKKIT-3792 - https://bukkit.atlassian.net/browse/BUKKIT-3792