Fork of Poseidon providing Bukkit #1060 to older Beta versions (b1.0-b1.7.3)
keii.dev
1package org.bukkit;
2
3import org.bukkit.block.Biome;
4import org.bukkit.block.Block;
5import org.bukkit.entity.*;
6import org.bukkit.event.entity.EntityDamageEvent;
7import org.bukkit.generator.BlockPopulator;
8import org.bukkit.generator.ChunkGenerator;
9import org.bukkit.inventory.ItemStack;
10import org.bukkit.util.Vector;
11
12import java.util.HashMap;
13import java.util.List;
14import java.util.Map;
15import java.util.UUID;
16
17/**
18 * Represents a world, which may contain entities, chunks and blocks
19 */
20public interface World {
21
22 /**
23 * Gets the {@link Block} at the given coordinates
24 *
25 * @param x X-coordinate of the block
26 * @param y Y-coordinate of the block
27 * @param z Z-coordinate of the block
28 * @return Block at the given coordinates
29 * @see #getBlockTypeIdAt(int, int, int) Returns the current type ID of the block
30 */
31 public Block getBlockAt(int x, int y, int z);
32
33 /**
34 * Gets the {@link Block} at the given {@link Location}
35 *
36 * @param location Location of the block
37 * @return Block at the given location
38 * @see #getBlockTypeIdAt(org.bukkit.Location) Returns the current type ID of the block
39 */
40 public Block getBlockAt(Location location);
41
42 /**
43 * Gets the block type ID at the given coordinates
44 *
45 * @param x X-coordinate of the block
46 * @param y Y-coordinate of the block
47 * @param z Z-coordinate of the block
48 * @return Type ID of the block at the given coordinates
49 * @see #getBlockAt(int, int, int) Returns a live Block object at the given location
50 */
51 public int getBlockTypeIdAt(int x, int y, int z);
52
53 /**
54 * Gets the block type ID at the given {@link Location}
55 *
56 * @param location Location of the block
57 * @return Type ID of the block at the given location
58 * @see #getBlockAt(org.bukkit.Location) Returns a live Block object at the given location
59 */
60 public int getBlockTypeIdAt(Location location);
61
62 /**
63 * Gets the highest non-air coordinate at the given coordinates
64 *
65 * @param x X-coordinate of the blocks
66 * @param z Z-coordinate of the blocks
67 * @return Y-coordinate of the highest non-air block
68 */
69 public int getHighestBlockYAt(int x, int z);
70
71 /**
72 * Gets the highest non-air coordinate at the given {@link Location}
73 *
74 * @param location Location of the blocks
75 * @return Y-coordinate of the highest non-air block
76 */
77 public int getHighestBlockYAt(Location location);
78
79 /**
80 * Gets the highest non-empty block at the given coordinates
81 *
82 * @param x X-coordinate of the block
83 * @param z Z-coordinate of the block
84 * @return Highest non-empty block
85 */
86 public Block getHighestBlockAt(int x, int z);
87
88 /**
89 * Gets the highest non-empty block at the given coordinates
90 *
91 * @param location Coordinates to get the highest block
92 * @return Highest non-empty block
93 */
94 public Block getHighestBlockAt(Location location);
95
96 /**
97 * Gets the {@link Chunk} at the given coordinates
98 *
99 * @param x X-coordinate of the chunk
100 * @param z Z-coordinate of the chunk
101 * @return Chunk at the given coordinates
102 */
103 public Chunk getChunkAt(int x, int z);
104
105 /**
106 * Gets the {@link Chunk} at the given {@link Location}
107 *
108 * @param location Location of the chunk
109 * @return Chunk at the given location
110 */
111 public Chunk getChunkAt(Location location);
112
113 /**
114 * Gets the {@link Chunk} that contains the given {@link Block}
115 *
116 * @param block Block to get the containing chunk from
117 * @return The chunk that contains the given block
118 */
119 public Chunk getChunkAt(Block block);
120
121 /**
122 * Checks if the specified {@link Chunk} is loaded
123 *
124 * @param chunk The chunk to check
125 * @return true if the chunk is loaded, otherwise false
126 */
127 public boolean isChunkLoaded(Chunk chunk);
128
129 /**
130 * Gets an array of all loaded {@link Chunk}s
131 *
132 * @return Chunk[] containing all loaded chunks
133 */
134 public Chunk[] getLoadedChunks();
135
136 /**
137 * Loads the specified {@link Chunk}
138 *
139 * @param chunk The chunk to load
140 */
141 public void loadChunk(Chunk chunk);
142
143 /**
144 * Checks if the {@link Chunk} at the specified coordinates is loaded
145 *
146 * @param x X-coordinate of the chunk
147 * @param z Z-coordinate of the chunk
148 * @return true if the chunk is loaded, otherwise false
149 */
150 public boolean isChunkLoaded(int x, int z);
151
152 /**
153 * Loads the {@link Chunk} at the specified coordinates
154 * <p>
155 * If the chunk does not exist, it will be generated.
156 * This method is analogous to {@link #loadChunk(int, int, boolean)} where generate is true.
157 *
158 * @param x X-coordinate of the chunk
159 * @param z Z-coordinate of the chunk
160 */
161 public void loadChunk(int x, int z);
162
163 /**
164 * Loads the {@link Chunk} at the specified coordinates
165 *
166 * @param x X-coordinate of the chunk
167 * @param z Z-coordinate of the chunk
168 * @param generate Whether or not to generate a chunk if it doesn't already exist
169 * @return true if the chunk has loaded successfully, otherwise false
170 */
171 public boolean loadChunk(int x, int z, boolean generate);
172
173 /**
174 * Safely unloads and saves the {@link Chunk} at the specified coordinates
175 * <p>
176 * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true
177 *
178 * @param chunk the chunk to unload
179 * @return true if the chunk has unloaded successfully, otherwise false
180 */
181 public boolean unloadChunk(Chunk chunk);
182
183 /**
184 * Safely unloads and saves the {@link Chunk} at the specified coordinates
185 * <p>
186 * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true
187 *
188 * @param x X-coordinate of the chunk
189 * @param z Z-coordinate of the chunk
190 * @return true if the chunk has unloaded successfully, otherwise false
191 */
192 public boolean unloadChunk(int x, int z);
193
194 /**
195 * Safely unloads and optionally saves the {@link Chunk} at the specified coordinates
196 * <p>
197 * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where save is true
198 *
199 * @param x X-coordinate of the chunk
200 * @param z Z-coordinate of the chunk
201 * @param save Whether or not to save the chunk
202 * @return true if the chunk has unloaded successfully, otherwise false
203 */
204 public boolean unloadChunk(int x, int z, boolean save);
205
206 /**
207 * Unloads and optionally saves the {@link Chunk} at the specified coordinates
208 *
209 * @param x X-coordinate of the chunk
210 * @param z Z-coordinate of the chunk
211 * @param save Controls whether the chunk is saved
212 * @param safe Controls whether to unload the chunk when players are nearby
213 * @return true if the chunk has unloaded successfully, otherwise false
214 */
215 public boolean unloadChunk(int x, int z, boolean save, boolean safe);
216
217 /**
218 * Safely queues the {@link Chunk} at the specified coordinates for unloading
219 * <p>
220 * This method is analogous to {@link #unloadChunkRequest(int, int, boolean)} where safe is true
221 *
222 * @param x X-coordinate of the chunk
223 * @param z Z-coordinate of the chunk
224 * @return true is the queue attempt was successful, otherwise false
225 */
226 public boolean unloadChunkRequest(int x, int z);
227
228 /**
229 * Queues the {@link Chunk} at the specified coordinates for unloading
230 *
231 * @param x X-coordinate of the chunk
232 * @param z Z-coordinate of the chunk
233 * @param safe Controls whether to queue the chunk when players are nearby
234 * @return Whether the chunk was actually queued
235 */
236 public boolean unloadChunkRequest(int x, int z, boolean safe);
237
238 /**
239 * Regenerates the {@link Chunk} at the specified coordinates
240 *
241 * @param x X-coordinate of the chunk
242 * @param z Z-coordinate of the chunk
243 * @return Whether the chunk was actually regenerated
244 */
245 public boolean regenerateChunk(int x, int z);
246
247 /**
248 * Resends the {@link Chunk} to all clients
249 *
250 * @param x X-coordinate of the chunk
251 * @param z Z-coordinate of the chunk
252 * @return Whether the chunk was actually refreshed
253 */
254 public boolean refreshChunk(int x, int z);
255
256 /**
257 * Drops an item at the specified {@link Location}
258 *
259 * @param location Location to drop the item
260 * @param item ItemStack to drop
261 * @return ItemDrop entity created as a result of this method
262 */
263 public Item dropItem(Location location, ItemStack item);
264
265 /**
266 * Drops an item at the specified {@link Location} with a random offset
267 *
268 * @param location Location to drop the item
269 * @param item ItemStack to drop
270 * @return ItemDrop entity created as a result of this method
271 */
272 public Item dropItemNaturally(Location location, ItemStack item);
273
274 /**
275 * Creates an {@link Arrow} entity at the given {@link Location}
276 *
277 * @param location Location to spawn the arrow
278 * @param velocity Velocity to shoot the arrow in
279 * @param speed Speed of the arrow. A recommend speed is 0.6
280 * @param spread Spread of the arrow. A recommend spread is 12
281 * @return Arrow entity spawned as a result of this method
282 */
283 public Arrow spawnArrow(Location location, Vector velocity, float speed, float spread);
284
285 /**
286 * Creates a tree at the given {@link Location}
287 *
288 * @param location Location to spawn the tree
289 * @param type Type of the tree to create
290 * @return true if the tree was created successfully, otherwise false
291 */
292 public boolean generateTree(Location location, TreeType type);
293
294 /**
295 * Creates a tree at the given {@link Location}
296 *
297 * @param loc Location to spawn the tree
298 * @param type Type of the tree to create
299 * @param delegate A class to call for each block changed as a result of this method
300 * @return true if the tree was created successfully, otherwise false
301 */
302 public boolean generateTree(Location loc, TreeType type, BlockChangeDelegate delegate);
303
304 /**
305 * Creates a creature at the given {@link Location}
306 *
307 * @param loc The location to spawn the creature
308 * @param type The creature to spawn
309 * @return Resulting LivingEntity of this method, or null if it was unsuccessful
310 */
311 public LivingEntity spawnCreature(Location loc, CreatureType type);
312
313 /**
314 * Strikes lightning at the given {@link Location}
315 *
316 * @param loc The location to strike lightning
317 * @return
318 */
319 public LightningStrike strikeLightning(Location loc);
320
321 /**
322 * Strikes lightning at the given {@link Location} without doing damage
323 *
324 * @param loc The location to strike lightning
325 * @return
326 */
327 public LightningStrike strikeLightningEffect(Location loc);
328
329 /**
330 * Get a list of all entities in this World
331 *
332 * @return A List of all Entities currently residing in this world
333 */
334 public List<Entity> getEntities();
335
336 /**
337 * Get a list of all living entities in this World
338 *
339 * @return A List of all LivingEntities currently residing in this world
340 */
341 public List<LivingEntity> getLivingEntities();
342
343 /**
344 * Get a list of all players in this World
345 *
346 * @return A list of all Players currently residing in this world
347 */
348 public List<Player> getPlayers();
349
350 /**
351 * Gets the unique name of this world
352 *
353 * @return Name of this world
354 */
355 public String getName();
356
357 /**
358 * Gets the Unique ID of this world
359 *
360 * @return Unique ID of this world.
361 */
362 public UUID getUID();
363
364 /**
365 * Gets a semi-unique identifier for this world.
366 * <p>
367 * While it is highly unlikely that this may be shared with another World,
368 * it is not guaranteed to be unique
369 *
370 * @return Id of this world
371 * @deprecated Replaced with {@link #getUID()}
372 */
373 @Deprecated
374 public long getId();
375
376 /**
377 * Gets the default spawn {@link Location} of this world
378 *
379 * @return The spawn location of this world
380 */
381 public Location getSpawnLocation();
382
383 /**
384 * Sets the spawn location of the world
385 *
386 * @param x
387 * @param y
388 * @param z
389 * @return True if it was successfully set.
390 */
391 public boolean setSpawnLocation(int x, int y, int z);
392
393 /**
394 * Gets the relative in-game time of this world.
395 * <p>
396 * The relative time is analogous to hours * 1000
397 *
398 * @return The current relative time
399 * @see #getFullTime() Returns an absolute time of this world
400 */
401 public long getTime();
402
403 /**
404 * Sets the relative in-game time on the server.
405 * <p>
406 * The relative time is analogous to hours * 1000
407 * <br /><br />
408 * Note that setting the relative time below the current relative time will
409 * actually move the clock forward a day. If you require to rewind time, please
410 * see setFullTime
411 *
412 * @param time The new relative time to set the in-game time to (in hours*1000)
413 * @see #setFullTime(long) Sets the absolute time of this world
414 */
415 public void setTime(long time);
416
417 /**
418 * Gets the full in-game time on this world
419 *
420 * @return The current absolute time
421 * @see #getTime() Returns a relative time of this world
422 */
423 public long getFullTime();
424
425 /**
426 * Sets the in-game time on the server
427 * <br /><br />
428 * Note that this sets the full time of the world, which may cause adverse
429 * effects such as breaking redstone clocks and any scheduled events
430 *
431 * @param time The new absolute time to set this world to
432 * @see #setTime(long) Sets the relative time of this world
433 */
434 public void setFullTime(long time);
435
436 /**
437 * Returns whether the world has an ongoing storm.
438 *
439 * @return Whether there is an ongoing storm
440 */
441 public boolean hasStorm();
442
443 /**
444 * Set whether there is a storm. A duration will be set for the new
445 * current conditions.
446 *
447 * @param hasStorm Whether there is rain and snow
448 */
449 public void setStorm(boolean hasStorm);
450
451 /**
452 * Get the remaining time in ticks of the current conditions.
453 *
454 * @return Time in ticks
455 */
456 public int getWeatherDuration();
457
458 /**
459 * Set the remaining time in ticks of the current conditions.
460 *
461 * @param duration Time in ticks
462 */
463 public void setWeatherDuration(int duration);
464
465 /**
466 * Returns whether there is thunder.
467 *
468 * @return Whether there is thunder
469 */
470 public boolean isThundering();
471
472 /**
473 * Set whether it is thundering.
474 *
475 * @param thundering Whether it is thundering
476 */
477 public void setThundering(boolean thundering);
478
479 /**
480 * Get the thundering duration.
481 *
482 * @return Duration in ticks
483 */
484 public int getThunderDuration();
485
486 /**
487 * Set the thundering duration.
488 *
489 * @param duration Duration in ticks
490 */
491 public void setThunderDuration(int duration);
492
493 /**
494 * Creates explosion at given coordinates with given power
495 *
496 * @param x
497 * @param y
498 * @param z
499 * @param power The power of explosion, where 4F is TNT
500 * @return false if explosion was canceled, otherwise true
501 */
502 public boolean createExplosion(double x, double y, double z, float power);
503
504 /**
505 * Creates explosion at given coordinates with given power and optionally setting
506 * blocks on fire.
507 *
508 * @param x
509 * @param y
510 * @param z
511 * @param power The power of explosion, where 4F is TNT
512 * @param setFire Whether or not to set blocks on fire
513 * @return false if explosion was canceled, otherwise true
514 */
515 public boolean createExplosion(double x, double y, double z, float power, boolean setFire);
516
517 /**
518 * Creates explosion at given coordinates with given power and DamageCause and optionally setting
519 * blocks on fire.
520 *
521 * @param x
522 * @param y
523 * @param z
524 * @param power The power of explosion, where 4F is TNT
525 * @param setFire Whether or not to set blocks on fire
526 * @param customDamageCause The DamageCause to use for the explosion
527 * @return false if explosion was canceled, otherwise true
528 */
529 public boolean createExplosion(double x, double y, double z, float power, boolean setFire, EntityDamageEvent.DamageCause customDamageCause);
530
531 /**
532 * Creates explosion at given coordinates with given power
533 *
534 * @param loc
535 * @param power The power of explosion, where 4F is TNT
536 * @return false if explosion was canceled, otherwise true
537 */
538 public boolean createExplosion(Location loc, float power);
539
540 /**
541 * Creates explosion at given coordinates with given power and optionally setting
542 * blocks on fire.
543 *
544 * @param loc
545 * @param power The power of explosion, where 4F is TNT
546 * @param setFire Whether or not to set blocks on fire
547 * @return false if explosion was canceled, otherwise true
548 */
549 public boolean createExplosion(Location loc, float power, boolean setFire);
550
551 /**
552 * Creates explosion at given coordinates with given power and DamageCause and optionally setting
553 * blocks on fire.
554 *
555 * @param loc
556 * @param power The power of explosion, where 4F is TNT
557 * @param setFire Whether or not to set blocks on fire
558 * @param customDamageCause The DamageCause to use for the explosion
559 * @return false if explosion was canceled, otherwise true
560 */
561 public boolean createExplosion(Location loc, float power, boolean setFire, EntityDamageEvent.DamageCause customDamageCause);
562
563 /**
564 * Gets the {@link Environment} type of this world
565 *
566 * @return This worlds Environment type
567 */
568 public Environment getEnvironment();
569
570 /**
571 * Gets the Seed for this world.
572 *
573 * @return This worlds Seed
574 */
575 public long getSeed();
576
577 /**
578 * Gets the current PVP setting for this world.
579 *
580 * @return
581 */
582 public boolean getPVP();
583
584 /**
585 * Sets the PVP setting for this world.
586 *
587 * @param pvp True/False whether PVP should be Enabled.
588 */
589 public void setPVP(boolean pvp);
590
591 /**
592 * Gets the chunk generator for this world
593 *
594 * @return ChunkGenerator associated with this world
595 */
596 public ChunkGenerator getGenerator();
597
598 /**
599 * Saves world to disk
600 */
601 public void save();
602
603 /**
604 * Gets a list of all applied {@link BlockPopulator}s for this World
605 *
606 * @return List containing any or none BlockPopulators
607 */
608 public List<BlockPopulator> getPopulators();
609
610 /**
611 * Spawn an entity of a specific class at the given {@link Location}
612 *
613 * @param location the {@link Location} to spawn the entity at
614 * @param clazz the class of the {@link Entity} to spawn
615 * @return an instance of the spawned {@link Entity}
616 * @throws an {@link IllegalArgumentException} if either parameter is null or the {@link Entity} requested cannot be spawned
617 */
618 public <T extends Entity> T spawn(Location location, Class<T> clazz) throws IllegalArgumentException;
619
620 /**
621 * Plays an effect to all players within a default radius around a given location.
622 *
623 * @param location the {@link Location} around which players must be to hear the sound
624 * @param effect the {@link Effect}
625 * @param data a data bit needed for the RECORD_PLAY, SMOKE, and STEP_SOUND sounds
626 */
627 public void playEffect(Location location, Effect effect, int data);
628
629 /**
630 * Plays an effect to all players within a given radius around a location.
631 *
632 * @param location the {@link Location} around which players must be to hear the effect
633 * @param effect the {@link Effect}
634 * @param data a data bit needed for the RECORD_PLAY, SMOKE, and STEP effects
635 * @param radius the radius around the location
636 */
637 public void playEffect(Location location, Effect effect, int data, int radius);
638
639 /**
640 * Get empty chunk snapshot (equivalent to all air blocks), optionally including valid biome
641 * data. Used for representing an ungenerated chunk, or for fetching only biome data without loading a chunk.
642 *
643 * @param x - chunk x coordinate
644 * @param z - chunk z coordinate
645 * @param includeBiome - if true, snapshot includes per-coordinate biome type
646 * @param includeBiomeTempRain - if true, snapshot includes per-coordinate raw biome temperature and rainfall
647 */
648 public ChunkSnapshot getEmptyChunkSnapshot(int x, int z, boolean includeBiome, boolean includeBiomeTempRain);
649
650 /**
651 * Sets the spawn flags for this.
652 *
653 * @param allowMonsters - if true, monsters are allowed to spawn in this world.
654 * @param allowAnimals - if true, animals are allowed to spawn in this world.
655 */
656 public void setSpawnFlags(boolean allowMonsters, boolean allowAnimals);
657
658 /**
659 * Gets whether animals can spawn in this world.
660 *
661 * @return whether animals can spawn in this world.
662 */
663 public boolean getAllowAnimals();
664
665 /**
666 * Gets whether monsters can spawn in this world.
667 *
668 * @return whether monsters can spawn in this world.
669 */
670 public boolean getAllowMonsters();
671
672 /**
673 * Gets the biome for the given block coordinates.
674 * <p>
675 * It is safe to run this method when the block does not exist, it will not create the block.
676 *
677 * @param x X coordinate of the block
678 * @param z Z coordinate of the block
679 * @return Biome of the requested block
680 */
681 public Biome getBiome(int x, int z);
682
683 /**
684 * Gets the temperature for the given block coordinates.
685 * <p>
686 * It is safe to run this method when the block does not exist, it will not create the block.
687 *
688 * @param x X coordinate of the block
689 * @param z Z coordinate of the block
690 * @return Temperature of the requested block
691 */
692 public double getTemperature(int x, int z);
693
694 /**
695 * Gets the humidity for the given block coordinates.
696 * <p>
697 * It is safe to run this method when the block does not exist, it will not create the block.
698 *
699 * @param x X coordinate of the block
700 * @param z Z coordinate of the block
701 * @return Humidity of the requested block
702 */
703 public double getHumidity(int x, int z);
704
705 /**
706 * Gets the maximum height of this world.
707 * <p>
708 * If the max height is 100, there are only blocks from y=0 to y=99.
709 *
710 * @return Maximum height of the world
711 */
712 public int getMaxHeight();
713
714 /**
715 * Gets whether the world's spawn area should be kept loaded into memory or not.
716 *
717 * @return true if the world's spawn area will be kept loaded into memory.
718 */
719 public boolean getKeepSpawnInMemory();
720
721 /**
722 * Sets whether the world's spawn area should be kept loaded into memory or not.
723 *
724 * @param keepLoaded if true then the world's spawn area will be kept loaded into memory.
725 */
726 public void setKeepSpawnInMemory(boolean keepLoaded);
727
728 /**
729 * Gets whether or not the world will automatically save
730 *
731 * @return true if the world will automatically save, otherwise false
732 */
733 public boolean isAutoSave();
734
735 /**
736 * Sets whether or not the world will automatically save
737 *
738 * @param value true if the world should automatically save, otherwise false
739 */
740 public void setAutoSave(boolean value);
741
742 /**
743 * Represents various map environment types that a world may be
744 */
745 public enum Environment {
746 /**
747 * Represents the "normal"/"surface world" map
748 */
749 NORMAL(0),
750 /**
751 * Represents a nether based map ("hell")
752 */
753 NETHER(-1),
754 /**
755 * Represents a sky-lands based map ("heaven")
756 */
757 SKYLANDS(1);
758
759 private final int id;
760 private static final Map<Integer, Environment> lookup = new HashMap<Integer, Environment>();
761
762 private Environment(int id) {
763 this.id = id;
764 }
765
766 /**
767 * Gets the dimension ID of this environment
768 *
769 * @return dimension ID
770 */
771 public int getId() {
772 return id;
773 }
774
775 public static Environment getEnvironment(int id) {
776 return lookup.get(id);
777 }
778
779 static {
780 for (Environment env : values()) {
781 lookup.put(env.getId(), env);
782 }
783 }
784 }
785}