Commits

md_5 authored 72c26058df3 
SPIGOT-2741: Deprecate legacy particle API
No tags
850da7e0741
master

Bukkit-Patches/0006-Add-Particle-API.patch

Modified
1 -From 95a866dfe8f57e056eed67c0c23427991abf23ad Mon Sep 17 00:00:00 2001
1 +From 6d92033dc361464b24daaabd765b4486798cc09c Mon Sep 17 00:00:00 2001
2 2 From: md_5 <md_5@live.com.au>
3 3 Date: Sun, 2 Jun 2013 15:57:09 +1000
4 4 Subject: [PATCH] Add Particle API
5 5 ​
6 6 ​
7 7 diff --git a/src/main/java/org/bukkit/Effect.java b/src/main/java/org/bukkit/Effect.java
8 -index ba7dc49..b0f6da7 100644
8 +index ba7dc49..a803228 100644
9 9 --- a/src/main/java/org/bukkit/Effect.java
10 10 +++ b/src/main/java/org/bukkit/Effect.java
11 11 @@ -5,6 +5,7 @@ import java.util.Map;
12 12 import com.google.common.collect.Maps;
13 13
14 14 import org.bukkit.block.BlockFace;
15 15 +import org.bukkit.material.MaterialData;
16 16 import org.bukkit.potion.Potion;
17 17
18 18 /**
19 -@@ -196,27 +197,188 @@ public enum Effect {
19 +@@ -196,27 +197,258 @@ public enum Effect {
20 20 * The sound of an enderdragon growling
21 21 */
22 22 ENDERDRAGON_GROWL(3001, Type.SOUND),
23 23 + /**
24 24 + * The spark that comes off a fireworks
25 ++ * @deprecated Spigot specific API, use {@link Particle}.
25 26 + */
27 ++ @Deprecated
26 28 + FIREWORKS_SPARK("fireworksSpark", Type.PARTICLE),
27 29 + /**
28 30 + * Critical hit particles
31 ++ * @deprecated Spigot specific API, use {@link Particle}.
29 32 + */
33 ++ @Deprecated
30 34 + CRIT("crit", Type.PARTICLE),
31 35 + /**
32 36 + * Blue critical hit particles
37 ++ * @deprecated Spigot specific API, use {@link Particle}.
33 38 + */
39 ++ @Deprecated
34 40 + MAGIC_CRIT("magicCrit", Type.PARTICLE),
35 41 + /**
36 42 + * Multicolored potion effect particles
43 ++ * @deprecated Spigot specific API, use {@link Particle}.
37 44 + */
45 ++ @Deprecated
38 46 + POTION_SWIRL("mobSpell", Type.PARTICLE),
39 47 + /**
40 48 + * Multicolored potion effect particles that are slightly transparent
49 ++ * @deprecated Spigot specific API, use {@link Particle}.
41 50 + */
51 ++ @Deprecated
42 52 + POTION_SWIRL_TRANSPARENT("mobSpellAmbient", Type.PARTICLE),
43 53 + /**
44 54 + * A puff of white potion swirls
55 ++ * @deprecated Spigot specific API, use {@link Particle}.
45 56 + */
57 ++ @Deprecated
46 58 + SPELL("spell", Type.PARTICLE),
47 59 + /**
48 60 + * A puff of white stars
61 ++ * @deprecated Spigot specific API, use {@link Particle}.
49 62 + */
63 ++ @Deprecated
50 64 + INSTANT_SPELL("instantSpell", Type.PARTICLE),
51 65 + /**
52 66 + * A puff of purple particles
67 ++ * @deprecated Spigot specific API, use {@link Particle}.
53 68 + */
69 ++ @Deprecated
54 70 + WITCH_MAGIC("witchMagic", Type.PARTICLE),
55 71 + /**
56 72 + * The note that appears above note blocks
73 ++ * @deprecated Spigot specific API, use {@link Particle}.
57 74 + */
75 ++ @Deprecated
58 76 + NOTE("note", Type.PARTICLE),
59 77 + /**
60 78 + * The particles shown at nether portals
79 ++ * @deprecated Spigot specific API, use {@link Particle}.
61 80 + */
81 ++ @Deprecated
62 82 + PORTAL("portal", Type.PARTICLE),
63 83 + /**
64 84 + * The symbols that fly towards the enchantment table
85 ++ * @deprecated Spigot specific API, use {@link Particle}.
65 86 + */
87 ++ @Deprecated
66 88 + FLYING_GLYPH("enchantmenttable", Type.PARTICLE),
67 89 + /**
68 90 + * Fire particles
91 ++ * @deprecated Spigot specific API, use {@link Particle}.
69 92 + */
93 ++ @Deprecated
70 94 + FLAME("flame", Type.PARTICLE),
71 95 + /**
72 96 + * The particles that pop out of lava
97 ++ * @deprecated Spigot specific API, use {@link Particle}.
73 98 + */
99 ++ @Deprecated
74 100 + LAVA_POP("lava", Type.PARTICLE),
75 101 + /**
76 102 + * A small gray square
103 ++ * @deprecated Spigot specific API, use {@link Particle}.
77 104 + */
105 ++ @Deprecated
78 106 + FOOTSTEP("footstep", Type.PARTICLE),
79 107 + /**
80 108 + * Water particles
109 ++ * @deprecated Spigot specific API, use {@link Particle}.
81 110 + */
111 ++ @Deprecated
82 112 + SPLASH("splash", Type.PARTICLE),
83 113 + /**
84 114 + * Smoke particles
115 ++ * @deprecated Spigot specific API, use {@link Particle}.
85 116 + */
117 ++ @Deprecated
86 118 + PARTICLE_SMOKE("smoke", Type.PARTICLE),
87 119 + /**
88 120 + * The biggest explosion particle effect
121 ++ * @deprecated Spigot specific API, use {@link Particle}.
89 122 + */
123 ++ @Deprecated
90 124 + EXPLOSION_HUGE("hugeexplosion", Type.PARTICLE),
91 125 + /**
92 126 + * A larger version of the explode particle
127 ++ * @deprecated Spigot specific API, use {@link Particle}.
93 128 + */
129 ++ @Deprecated
94 130 + EXPLOSION_LARGE("largeexplode", Type.PARTICLE),
95 131 + /**
96 132 + * Explosion particles
133 ++ * @deprecated Spigot specific API, use {@link Particle}.
97 134 + */
135 ++ @Deprecated
98 136 + EXPLOSION("explode", Type.PARTICLE),
99 137 + /**
100 138 + * Small gray particles
139 ++ * @deprecated Spigot specific API, use {@link Particle}.
101 140 + */
141 ++ @Deprecated
102 142 + VOID_FOG("depthsuspend", Type.PARTICLE),
103 143 + /**
104 144 + * Small gray particles
145 ++ * @deprecated Spigot specific API, use {@link Particle}.
105 146 + */
147 ++ @Deprecated
106 148 + SMALL_SMOKE("townaura", Type.PARTICLE),
107 149 + /**
108 150 + * A puff of white smoke
151 ++ * @deprecated Spigot specific API, use {@link Particle}.
109 152 + */
153 ++ @Deprecated
110 154 + CLOUD("cloud", Type.PARTICLE),
111 155 + /**
112 156 + * Multicolored dust particles
157 ++ * @deprecated Spigot specific API, use {@link Particle}.
113 158 + */
159 ++ @Deprecated
114 160 + COLOURED_DUST("reddust", Type.PARTICLE),
115 161 + /**
116 162 + * Snowball breaking
163 ++ * @deprecated Spigot specific API, use {@link Particle}.
117 164 + */
165 ++ @Deprecated
118 166 + SNOWBALL_BREAK("snowballpoof", Type.PARTICLE),
119 167 + /**
120 168 + * The water drip particle that appears on blocks under water
169 ++ * @deprecated Spigot specific API, use {@link Particle}.
121 170 + */
171 ++ @Deprecated
122 172 + WATERDRIP("dripWater", Type.PARTICLE),
123 173 + /**
124 174 + * The lava drip particle that appears on blocks under lava
175 ++ * @deprecated Spigot specific API, use {@link Particle}.
125 176 + */
177 ++ @Deprecated
126 178 + LAVADRIP("dripLava", Type.PARTICLE),
127 179 + /**
128 180 + * White particles
181 ++ * @deprecated Spigot specific API, use {@link Particle}.
129 182 + */
183 ++ @Deprecated
130 184 + SNOW_SHOVEL("snowshovel", Type.PARTICLE),
131 185 + /**
132 186 + * The particle shown when a slime jumps
187 ++ * @deprecated Spigot specific API, use {@link Particle}.
133 188 + */
189 ++ @Deprecated
134 190 + SLIME("slime", Type.PARTICLE),
135 191 + /**
136 192 + * The particle that appears when breading animals
193 ++ * @deprecated Spigot specific API, use {@link Particle}.
137 194 + */
195 ++ @Deprecated
138 196 + HEART("heart", Type.PARTICLE),
139 197 + /**
140 198 + * The particle that appears when hitting a villager
199 ++ * @deprecated Spigot specific API, use {@link Particle}.
141 200 + */
201 ++ @Deprecated
142 202 + VILLAGER_THUNDERCLOUD("angryVillager", Type.PARTICLE),
143 203 + /**
144 204 + * The particle that appears when trading with a villager
205 ++ * @deprecated Spigot specific API, use {@link Particle}.
145 206 + */
207 ++ @Deprecated
146 208 + HAPPY_VILLAGER("happyVillager", Type.PARTICLE),
147 209 + /**
148 210 + * The smoke particles that appears on blazes, minecarts
149 211 + * with furnaces and fire
212 ++ * @deprecated Spigot specific API, use {@link Particle}.
150 213 + */
214 ++ @Deprecated
151 215 + LARGE_SMOKE("largesmoke", Type.PARTICLE),
152 216 + /**
153 217 + * The particles generated when a tool breaks.
154 218 + * This particle requires a Material so that the client can select the correct texture.
219 ++ * @deprecated Spigot specific API, use {@link Particle}.
155 220 + */
221 ++ @Deprecated
156 222 + ITEM_BREAK("iconcrack", Type.PARTICLE, Material.class),
157 223 + /**
158 224 + * The particles generated while breaking a block.
159 225 + * This particle requires a Material and data value so that the client can select the correct texture.
226 ++ * @deprecated Spigot specific API, use {@link Particle}.
160 227 + */
228 ++ @Deprecated
161 229 + TILE_BREAK("blockcrack", Type.PARTICLE, MaterialData.class),
162 230 + /**
163 231 + * The particles generated while sprinting a block
164 232 + * This particle requires a Material and data value so that the client can select the correct texture.
233 ++ * @deprecated Spigot specific API, use {@link Particle}.
165 234 + */
235 ++ @Deprecated
166 236 + TILE_DUST("blockdust", Type.PARTICLE, MaterialData.class)
167 237 ;
168 238
169 239 private final int id;
170 240 private final Type type;
171 241 private final Class<?> data;
172 242 private static final Map<Integer, Effect> BY_ID = Maps.newHashMap();
173 243 + private static final Map<String, Effect> BY_NAME = Maps.newHashMap();
174 244 + private final String particleName;
175 245
201 271 }
202 272
203 273 /**
204 274 * Gets the ID for this effect.
205 275 *
206 276 - * @return ID of this effect
207 277 + * @return if this Effect isn't of type PARTICLE it returns ID of this effect
208 278 * @deprecated Magic value
209 279 */
210 280 @Deprecated
211 -@@ -225,6 +387,15 @@ public enum Effect {
281 +@@ -225,6 +457,17 @@ public enum Effect {
212 282 }
213 283
214 284 /**
215 285 + * Returns the effect's name. This returns null if the effect is not a particle
216 286 + *
217 287 + * @return The effect's name
288 ++ * @deprecated Spigot specific API, use {@link Particle}.
218 289 + */
290 ++ @Deprecated
219 291 + public String getName() {
220 292 + return particleName;
221 293 + }
222 294 +
223 295 + /**
224 296 * @return The type of the effect.
225 297 */
226 298 public Type getType() {
227 -@@ -232,8 +403,7 @@ public enum Effect {
299 +@@ -232,8 +475,7 @@ public enum Effect {
228 300 }
229 301
230 302 /**
231 303 - * @return The class which represents data for this effect, or null if
232 304 - * none
233 305 + * @return if this Effect isn't of type PARTICLE it returns the class which represents data for this effect, or null if none
234 306 */
235 307 public Class<?> getData() {
236 308 return this.data;
237 -@@ -253,12 +423,32 @@ public enum Effect {
309 +@@ -253,12 +495,34 @@ public enum Effect {
238 310
239 311 static {
240 312 for (Effect effect : values()) {
241 313 - BY_ID.put(effect.id, effect);
242 314 + if (effect.type != Type.PARTICLE) {
243 315 + BY_ID.put(effect.id, effect);
244 316 + }
245 317 + }
246 318 + }
247 319 +
248 320 + /**
249 321 + * Gets the Effect associated with the given name.
250 322 + *
251 323 + * @param name name of the Effect to return
252 324 + * @return Effect with the given name
325 ++ * @deprecated Spigot specific API, use {@link Particle}.
253 326 + */
327 ++ @Deprecated
254 328 + public static Effect getByName(String name) {
255 329 + return BY_NAME.get(name);
256 330 + }
257 331 +
258 332 + static {
259 333 + for (Effect effect : values()) {
260 334 + if (effect.type == Type.PARTICLE) {
261 335 + BY_NAME.put(effect.particleName, effect);
262 336 + }
263 337 }
264 338 }
265 339
266 340 /**
267 341 * Represents the type of an effect.
268 342 */
269 343 - public enum Type {SOUND, VISUAL}
270 344 + public enum Type {SOUND, VISUAL, PARTICLE}
271 345 }
272 346 diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
273 -index c14840a..f9eac3a 100644
347 +index c14840a..e0362bf 100644
274 348 --- a/src/main/java/org/bukkit/World.java
275 349 +++ b/src/main/java/org/bukkit/World.java
276 -@@ -1194,6 +1194,56 @@ public interface World extends PluginMessageRecipient, Metadatable {
350 +@@ -1194,6 +1194,60 @@ public interface World extends PluginMessageRecipient, Metadatable {
277 351 */
278 352 public boolean isGameRule(String rule);
279 353
280 354 + // Spigot start
281 355 + public class Spigot
282 356 + {
283 357 +
284 358 + /**
285 359 + * Plays an effect to all players within a default radius around a given
286 360 + * location.
287 361 + *
288 362 + * @param location the {@link Location} around which players must be to
289 363 + * see the effect
290 364 + * @param effect the {@link Effect}
291 365 + * @throws IllegalArgumentException if the location or effect is null.
292 366 + * It also throws when the effect requires a material or a material data
367 ++ * @deprecated Spigot specific API, use {@link Particle}.
293 368 + */
369 ++ @Deprecated
294 370 + public void playEffect(Location location, Effect effect)
295 371 + {
296 372 + throw new UnsupportedOperationException( "Not supported yet." );
297 373 + }
298 374 +
299 375 + /**
300 376 + * Plays an effect to all players within a default radius around a given
301 377 + * location. The effect will use the provided material (and material
302 378 + * data if required). The particle's position on the client will be the
303 379 + * given location, adjusted on each axis by a normal distribution with
310 386 + * see the effect
311 387 + * @param effect effect the {@link Effect}
312 388 + * @param id the item/block/data id for the effect
313 389 + * @param data the data value of the block/item for the effect
314 390 + * @param offsetX the amount to be randomly offset by in the X axis
315 391 + * @param offsetY the amount to be randomly offset by in the Y axis
316 392 + * @param offsetZ the amount to be randomly offset by in the Z axis
317 393 + * @param speed the speed of the particles
318 394 + * @param particleCount the number of particles
319 395 + * @param radius the radius around the location
396 ++ * @deprecated Spigot specific API, use {@link Particle}.
320 397 + */
398 ++ @Deprecated
321 399 + public void playEffect(Location location, Effect effect, int id, int data, float offsetX, float offsetY, float offsetZ, float speed, int particleCount, int radius)
322 400 + {
323 401 + throw new UnsupportedOperationException( "Not supported yet." );
324 402 + }
325 403 + }
326 404 +
327 405 + Spigot spigot();
328 406 + // Spigot end
329 407 +
330 408 /**
331 409 * Gets the world border for this world.
332 410 *
333 411 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
334 -index 7689c6d..b561769 100644
412 +index 7689c6d..65e89c4 100644
335 413 --- a/src/main/java/org/bukkit/entity/Player.java
336 414 +++ b/src/main/java/org/bukkit/entity/Player.java
337 -@@ -1300,6 +1300,11 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline
415 +@@ -1300,6 +1300,12 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline
338 416 {
339 417 throw new UnsupportedOperationException( "Not supported yet." );
340 418 }
341 419 +
420 ++ @Deprecated
342 421 + public void playEffect(Location location, Effect effect, int id, int data, float offsetX, float offsetY, float offsetZ, float speed, int particleCount, int radius)
343 422 + {
344 423 + throw new UnsupportedOperationException( "Not supported yet." );
345 424 + }
346 425 }
347 426
348 427 Spigot spigot();
349 428 diff --git a/src/test/java/org/bukkit/EffectTest.java b/src/test/java/org/bukkit/EffectTest.java
350 429 index 08aa71d..5217aec 100644
351 430 --- a/src/test/java/org/bukkit/EffectTest.java
357 436 - assertThat(Effect.getById(effect.getId()), is(effect));
358 437 + if (effect.getType() != Effect.Type.PARTICLE) {
359 438 + assertThat(Effect.getById(effect.getId()), is(effect));
360 439 + } else {
361 440 + assertThat(Effect.getByName(effect.getName()), is(effect));
362 441 + }
363 442 }
364 443 }
365 444 }
366 445 --
367 -2.7.4
446 +2.9.3
368 447 ​

Everything looks good. We'll let you know here if there's anything you should know about.

Add shortcut