GlowstoneMC/Glowkit — pull request #22 by SpaceManiac (2014-09-26 03:17:52+00:00)
Title: API for displaying particle effects

There is no method to display specific particle effects to the users like there are to play individual sounds (Sound) or special effects (Effect). A wide variety particle effects are not currently possible to display to players, and it would be useful to be able to display them.

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.

To address:
* [x] **In 1.8, particles now have int rather than string ids.** The String methods need to be removed.
* [ ] `usesMaterial`/`usesData` may now be the same thing.
* [ ] The particle list may need to be updated for 1.8.
* [ ] 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.
* [ ] 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.

**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-1024 - https://github.com/Bukkit/Bukkit/pull/1025 - Original Bukkit PR
~~CB-1334 - https://github.com/Bukkit/CraftBukkit/pull/1334 - Accompanying CraftBukkit 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~~