001 package org.bukkit;
002
003 import java.io.File;
004 import org.bukkit.generator.ChunkGenerator;
005 import java.util.Collection;
006 import java.util.HashMap;
007 import java.util.List;
008 import java.util.Map;
009 import java.util.UUID;
010
011 import org.bukkit.block.Biome;
012 import org.bukkit.block.Block;
013 import org.bukkit.entity.*;
014 import org.bukkit.generator.BlockPopulator;
015 import org.bukkit.inventory.ItemStack;
016 import org.bukkit.metadata.Metadatable;
017 import org.bukkit.plugin.messaging.PluginMessageRecipient;
018 import org.bukkit.util.Vector;
019
020 /**
021 * Represents a world, which may contain entities, chunks and blocks
022 */
023 public interface World extends PluginMessageRecipient, Metadatable {
024
025 /**
026 * Gets the {@link Block} at the given coordinates
027 *
028 * @param x X-coordinate of the block
029 * @param y Y-coordinate of the block
030 * @param z Z-coordinate of the block
031 * @return Block at the given coordinates
032 * @see #getBlockTypeIdAt(int, int, int) Returns the current type ID of
033 * the block
034 */
035 public Block getBlockAt(int x, int y, int z);
036
037 /**
038 * Gets the {@link Block} at the given {@link Location}
039 *
040 * @param location Location of the block
041 * @return Block at the given location
042 * @see #getBlockTypeIdAt(org.bukkit.Location) Returns the current type ID
043 * of the block
044 */
045 public Block getBlockAt(Location location);
046
047 /**
048 * Gets the block type ID at the given coordinates
049 *
050 * @param x X-coordinate of the block
051 * @param y Y-coordinate of the block
052 * @param z Z-coordinate of the block
053 * @return Type ID of the block at the given coordinates
054 * @see #getBlockAt(int, int, int) Returns a live Block object at the
055 * given location
056 * @deprecated Magic value
057 */
058 @Deprecated
059 public int getBlockTypeIdAt(int x, int y, int z);
060
061 /**
062 * Gets the block type ID at the given {@link Location}
063 *
064 * @param location Location of the block
065 * @return Type ID of the block at the given location
066 * @see #getBlockAt(org.bukkit.Location) Returns a live Block object at
067 * the given location
068 * @deprecated Magic value
069 */
070 @Deprecated
071 public int getBlockTypeIdAt(Location location);
072
073 /**
074 * Gets the highest non-air coordinate at the given coordinates
075 *
076 * @param x X-coordinate of the blocks
077 * @param z Z-coordinate of the blocks
078 * @return Y-coordinate of the highest non-air block
079 */
080 public int getHighestBlockYAt(int x, int z);
081
082 /**
083 * Gets the highest non-air coordinate at the given {@link Location}
084 *
085 * @param location Location of the blocks
086 * @return Y-coordinate of the highest non-air block
087 */
088 public int getHighestBlockYAt(Location location);
089
090 /**
091 * Gets the highest non-empty block at the given coordinates
092 *
093 * @param x X-coordinate of the block
094 * @param z Z-coordinate of the block
095 * @return Highest non-empty block
096 */
097 public Block getHighestBlockAt(int x, int z);
098
099 /**
100 * Gets the highest non-empty block at the given coordinates
101 *
102 * @param location Coordinates to get the highest block
103 * @return Highest non-empty block
104 */
105 public Block getHighestBlockAt(Location location);
106
107 /**
108 * Gets the {@link Chunk} at the given coordinates
109 *
110 * @param x X-coordinate of the chunk
111 * @param z Z-coordinate of the chunk
112 * @return Chunk at the given coordinates
113 */
114 public Chunk getChunkAt(int x, int z);
115
116 /**
117 * Gets the {@link Chunk} at the given {@link Location}
118 *
119 * @param location Location of the chunk
120 * @return Chunk at the given location
121 */
122 public Chunk getChunkAt(Location location);
123
124 /**
125 * Gets the {@link Chunk} that contains the given {@link Block}
126 *
127 * @param block Block to get the containing chunk from
128 * @return The chunk that contains the given block
129 */
130 public Chunk getChunkAt(Block block);
131
132 /**
133 * Checks if the specified {@link Chunk} is loaded
134 *
135 * @param chunk The chunk to check
136 * @return true if the chunk is loaded, otherwise false
137 */
138 public boolean isChunkLoaded(Chunk chunk);
139
140 /**
141 * Gets an array of all loaded {@link Chunk}s
142 *
143 * @return Chunk[] containing all loaded chunks
144 */
145 public Chunk[] getLoadedChunks();
146
147 /**
148 * Loads the specified {@link Chunk}
149 *
150 * @param chunk The chunk to load
151 */
152 public void loadChunk(Chunk chunk);
153
154 /**
155 * Checks if the {@link Chunk} at the specified coordinates is loaded
156 *
157 * @param x X-coordinate of the chunk
158 * @param z Z-coordinate of the chunk
159 * @return true if the chunk is loaded, otherwise false
160 */
161 public boolean isChunkLoaded(int x, int z);
162
163 /**
164 * Checks if the {@link Chunk} at the specified coordinates is loaded and
165 * in use by one or more players
166 *
167 * @param x X-coordinate of the chunk
168 * @param z Z-coordinate of the chunk
169 * @return true if the chunk is loaded and in use by one or more players,
170 * otherwise false
171 */
172 public boolean isChunkInUse(int x, int z);
173
174 /**
175 * Loads the {@link Chunk} at the specified coordinates
176 * <p>
177 * If the chunk does not exist, it will be generated.
178 * <p>
179 * This method is analogous to {@link #loadChunk(int, int, boolean)} where
180 * generate is true.
181 *
182 * @param x X-coordinate of the chunk
183 * @param z Z-coordinate of the chunk
184 */
185 public void loadChunk(int x, int z);
186
187 /**
188 * Loads the {@link Chunk} at the specified coordinates
189 *
190 * @param x X-coordinate of the chunk
191 * @param z Z-coordinate of the chunk
192 * @param generate Whether or not to generate a chunk if it doesn't
193 * already exist
194 * @return true if the chunk has loaded successfully, otherwise false
195 */
196 public boolean loadChunk(int x, int z, boolean generate);
197
198 /**
199 * Safely unloads and saves the {@link Chunk} at the specified coordinates
200 * <p>
201 * This method is analogous to {@link #unloadChunk(int, int, boolean,
202 * boolean)} where safe and saveis true
203 *
204 * @param chunk the chunk to unload
205 * @return true if the chunk has unloaded successfully, otherwise false
206 */
207 public boolean unloadChunk(Chunk chunk);
208
209 /**
210 * Safely unloads and saves the {@link Chunk} at the specified coordinates
211 * <p>
212 * This method is analogous to {@link #unloadChunk(int, int, boolean,
213 * boolean)} where safe and saveis true
214 *
215 * @param x X-coordinate of the chunk
216 * @param z Z-coordinate of the chunk
217 * @return true if the chunk has unloaded successfully, otherwise false
218 */
219 public boolean unloadChunk(int x, int z);
220
221 /**
222 * Safely unloads and optionally saves the {@link Chunk} at the specified
223 * coordinates
224 * <p>
225 * This method is analogous to {@link #unloadChunk(int, int, boolean,
226 * boolean)} where save is true
227 *
228 * @param x X-coordinate of the chunk
229 * @param z Z-coordinate of the chunk
230 * @param save Whether or not to save the chunk
231 * @return true if the chunk has unloaded successfully, otherwise false
232 */
233 public boolean unloadChunk(int x, int z, boolean save);
234
235 /**
236 * Unloads and optionally saves the {@link Chunk} at the specified
237 * coordinates
238 *
239 * @param x X-coordinate of the chunk
240 * @param z Z-coordinate of the chunk
241 * @param save Controls whether the chunk is saved
242 * @param safe Controls whether to unload the chunk when players are
243 * nearby
244 * @return true if the chunk has unloaded successfully, otherwise false
245 */
246 public boolean unloadChunk(int x, int z, boolean save, boolean safe);
247
248 /**
249 * Safely queues the {@link Chunk} at the specified coordinates for
250 * unloading
251 * <p>
252 * This method is analogous to {@link #unloadChunkRequest(int, int,
253 * boolean)} where safe is true
254 *
255 * @param x X-coordinate of the chunk
256 * @param z Z-coordinate of the chunk
257 * @return true is the queue attempt was successful, otherwise false
258 */
259 public boolean unloadChunkRequest(int x, int z);
260
261 /**
262 * Queues the {@link Chunk} at the specified coordinates for unloading
263 *
264 * @param x X-coordinate of the chunk
265 * @param z Z-coordinate of the chunk
266 * @param safe Controls whether to queue the chunk when players are nearby
267 * @return Whether the chunk was actually queued
268 */
269 public boolean unloadChunkRequest(int x, int z, boolean safe);
270
271 /**
272 * Regenerates the {@link Chunk} at the specified coordinates
273 *
274 * @param x X-coordinate of the chunk
275 * @param z Z-coordinate of the chunk
276 * @return Whether the chunk was actually regenerated
277 */
278 public boolean regenerateChunk(int x, int z);
279
280 /**
281 * Resends the {@link Chunk} to all clients
282 *
283 * @param x X-coordinate of the chunk
284 * @param z Z-coordinate of the chunk
285 * @return Whether the chunk was actually refreshed
286 */
287 public boolean refreshChunk(int x, int z);
288
289 /**
290 * Drops an item at the specified {@link Location}
291 *
292 * @param location Location to drop the item
293 * @param item ItemStack to drop
294 * @return ItemDrop entity created as a result of this method
295 */
296 public Item dropItem(Location location, ItemStack item);
297
298 /**
299 * Drops an item at the specified {@link Location} with a random offset
300 *
301 * @param location Location to drop the item
302 * @param item ItemStack to drop
303 * @return ItemDrop entity created as a result of this method
304 */
305 public Item dropItemNaturally(Location location, ItemStack item);
306
307 /**
308 * Creates an {@link Arrow} entity at the given {@link Location}
309 *
310 * @param location Location to spawn the arrow
311 * @param direction Direction to shoot the arrow in
312 * @param speed Speed of the arrow. A recommend speed is 0.6
313 * @param spread Spread of the arrow. A recommend spread is 12
314 * @return Arrow entity spawned as a result of this method
315 */
316 public Arrow spawnArrow(Location location, Vector direction, float speed, float spread);
317
318 /**
319 * Creates a tree at the given {@link Location}
320 *
321 * @param location Location to spawn the tree
322 * @param type Type of the tree to create
323 * @return true if the tree was created successfully, otherwise false
324 */
325 public boolean generateTree(Location location, TreeType type);
326
327 /**
328 * Creates a tree at the given {@link Location}
329 *
330 * @param loc Location to spawn the tree
331 * @param type Type of the tree to create
332 * @param delegate A class to call for each block changed as a result of
333 * this method
334 * @return true if the tree was created successfully, otherwise false
335 */
336 public boolean generateTree(Location loc, TreeType type, BlockChangeDelegate delegate);
337
338 /**
339 * Creates a entity at the given {@link Location}
340 *
341 * @param loc The location to spawn the entity
342 * @param type The entity to spawn
343 * @return Resulting Entity of this method, or null if it was unsuccessful
344 */
345 public Entity spawnEntity(Location loc, EntityType type);
346
347 /**
348 * Creates a creature at the given {@link Location}
349 *
350 * @param loc The location to spawn the creature
351 * @param type The creature to spawn
352 * @return Resulting LivingEntity of this method, or null if it was
353 * unsuccessful
354 * @deprecated Has issues spawning non LivingEntities. Use {@link
355 * #spawnEntity(Location, EntityType) spawnEntity} instead.
356 */
357 @Deprecated
358 public LivingEntity spawnCreature(Location loc, EntityType type);
359
360 /**
361 * Creates a creature at the given {@link Location}
362 *
363 * @param loc The location to spawn the creature
364 * @param type The creature to spawn
365 * @return Resulting LivingEntity of this method, or null if it was
366 * unsuccessful
367 */
368 @Deprecated
369 public LivingEntity spawnCreature(Location loc, CreatureType type);
370
371 /**
372 * Strikes lightning at the given {@link Location}
373 *
374 * @param loc The location to strike lightning
375 * @return The lightning entity.
376 */
377 public LightningStrike strikeLightning(Location loc);
378
379 /**
380 * Strikes lightning at the given {@link Location} without doing damage
381 *
382 * @param loc The location to strike lightning
383 * @return The lightning entity.
384 */
385 public LightningStrike strikeLightningEffect(Location loc);
386
387 /**
388 * Get a list of all entities in this World
389 *
390 * @return A List of all Entities currently residing in this world
391 */
392 public List<Entity> getEntities();
393
394 /**
395 * Get a list of all living entities in this World
396 *
397 * @return A List of all LivingEntities currently residing in this world
398 */
399 public List<LivingEntity> getLivingEntities();
400
401 /**
402 * Get a collection of all entities in this World matching the given
403 * class/interface
404 *
405 * @param classes The classes representing the types of entity to match
406 * @return A List of all Entities currently residing in this world that
407 * match the given class/interface
408 */
409 @Deprecated
410 public <T extends Entity> Collection<T> getEntitiesByClass(Class<T>... classes);
411
412 /**
413 * Get a collection of all entities in this World matching the given
414 * class/interface
415 *
416 * @param cls The class representing the type of entity to match
417 * @return A List of all Entities currently residing in this world that
418 * match the given class/interface
419 */
420 public <T extends Entity> Collection<T> getEntitiesByClass(Class<T> cls);
421
422 /**
423 * Get a collection of all entities in this World matching any of the
424 * given classes/interfaces
425 *
426 * @param classes The classes representing the types of entity to match
427 * @return A List of all Entities currently residing in this world that
428 * match one or more of the given classes/interfaces
429 */
430 public Collection<Entity> getEntitiesByClasses(Class<?>... classes);
431
432 /**
433 * Get a list of all players in this World
434 *
435 * @return A list of all Players currently residing in this world
436 */
437 public List<Player> getPlayers();
438
439 /**
440 * Gets the unique name of this world
441 *
442 * @return Name of this world
443 */
444 public String getName();
445
446 /**
447 * Gets the Unique ID of this world
448 *
449 * @return Unique ID of this world.
450 */
451 public UUID getUID();
452
453 /**
454 * Gets the default spawn {@link Location} of this world
455 *
456 * @return The spawn location of this world
457 */
458 public Location getSpawnLocation();
459
460 /**
461 * Sets the spawn location of the world
462 *
463 * @param x X coordinate
464 * @param y Y coordinate
465 * @param z Z coordinate
466 * @return True if it was successfully set.
467 */
468 public boolean setSpawnLocation(int x, int y, int z);
469
470 /**
471 * Gets the relative in-game time of this world.
472 * <p>
473 * The relative time is analogous to hours * 1000
474 *
475 * @return The current relative time
476 * @see #getFullTime() Returns an absolute time of this world
477 */
478 public long getTime();
479
480 /**
481 * Sets the relative in-game time on the server.
482 * <p>
483 * The relative time is analogous to hours * 1000
484 * <p>
485 * Note that setting the relative time below the current relative time
486 * will actually move the clock forward a day. If you require to rewind
487 * time, please see {@link #setFullTime(long)}
488 *
489 * @param time The new relative time to set the in-game time to (in
490 * hours*1000)
491 * @see #setFullTime(long) Sets the absolute time of this world
492 */
493 public void setTime(long time);
494
495 /**
496 * Gets the full in-game time on this world
497 *
498 * @return The current absolute time
499 * @see #getTime() Returns a relative time of this world
500 */
501 public long getFullTime();
502
503 /**
504 * Sets the in-game time on the server
505 * <p>
506 * Note that this sets the full time of the world, which may cause adverse
507 * effects such as breaking redstone clocks and any scheduled events
508 *
509 * @param time The new absolute time to set this world to
510 * @see #setTime(long) Sets the relative time of this world
511 */
512 public void setFullTime(long time);
513
514 /**
515 * Returns whether the world has an ongoing storm.
516 *
517 * @return Whether there is an ongoing storm
518 */
519 public boolean hasStorm();
520
521 /**
522 * Set whether there is a storm. A duration will be set for the new
523 * current conditions.
524 *
525 * @param hasStorm Whether there is rain and snow
526 */
527 public void setStorm(boolean hasStorm);
528
529 /**
530 * Get the remaining time in ticks of the current conditions.
531 *
532 * @return Time in ticks
533 */
534 public int getWeatherDuration();
535
536 /**
537 * Set the remaining time in ticks of the current conditions.
538 *
539 * @param duration Time in ticks
540 */
541 public void setWeatherDuration(int duration);
542
543 /**
544 * Returns whether there is thunder.
545 *
546 * @return Whether there is thunder
547 */
548 public boolean isThundering();
549
550 /**
551 * Set whether it is thundering.
552 *
553 * @param thundering Whether it is thundering
554 */
555 public void setThundering(boolean thundering);
556
557 /**
558 * Get the thundering duration.
559 *
560 * @return Duration in ticks
561 */
562 public int getThunderDuration();
563
564 /**
565 * Set the thundering duration.
566 *
567 * @param duration Duration in ticks
568 */
569 public void setThunderDuration(int duration);
570
571 /**
572 * Creates explosion at given coordinates with given power
573 *
574 * @param x X coordinate
575 * @param y Y coordinate
576 * @param z Z coordinate
577 * @param power The power of explosion, where 4F is TNT
578 * @return false if explosion was canceled, otherwise true
579 */
580 public boolean createExplosion(double x, double y, double z, float power);
581
582 /**
583 * Creates explosion at given coordinates with given power and optionally
584 * setting blocks on fire.
585 *
586 * @param x X coordinate
587 * @param y Y coordinate
588 * @param z Z coordinate
589 * @param power The power of explosion, where 4F is TNT
590 * @param setFire Whether or not to set blocks on fire
591 * @return false if explosion was canceled, otherwise true
592 */
593 public boolean createExplosion(double x, double y, double z, float power, boolean setFire);
594
595 /**
596 * Creates explosion at given coordinates with given power and optionally
597 * setting blocks on fire or breaking blocks.
598 *
599 * @param x X coordinate
600 * @param y Y coordinate
601 * @param z Z coordinate
602 * @param power The power of explosion, where 4F is TNT
603 * @param setFire Whether or not to set blocks on fire
604 * @param breakBlocks Whether or not to have blocks be destroyed
605 * @return false if explosion was canceled, otherwise true
606 */
607 public boolean createExplosion(double x, double y, double z, float power, boolean setFire, boolean breakBlocks);
608
609 /**
610 * Creates explosion at given coordinates with given power
611 *
612 * @param loc Location to blow up
613 * @param power The power of explosion, where 4F is TNT
614 * @return false if explosion was canceled, otherwise true
615 */
616 public boolean createExplosion(Location loc, float power);
617
618 /**
619 * Creates explosion at given coordinates with given power and optionally
620 * setting blocks on fire.
621 *
622 * @param loc Location to blow up
623 * @param power The power of explosion, where 4F is TNT
624 * @param setFire Whether or not to set blocks on fire
625 * @return false if explosion was canceled, otherwise true
626 */
627 public boolean createExplosion(Location loc, float power, boolean setFire);
628
629 /**
630 * Gets the {@link Environment} type of this world
631 *
632 * @return This worlds Environment type
633 */
634 public Environment getEnvironment();
635
636 /**
637 * Gets the Seed for this world.
638 *
639 * @return This worlds Seed
640 */
641 public long getSeed();
642
643 /**
644 * Gets the current PVP setting for this world.
645 *
646 * @return True if PVP is enabled
647 */
648 public boolean getPVP();
649
650 /**
651 * Sets the PVP setting for this world.
652 *
653 * @param pvp True/False whether PVP should be Enabled.
654 */
655 public void setPVP(boolean pvp);
656
657 /**
658 * Gets the chunk generator for this world
659 *
660 * @return ChunkGenerator associated with this world
661 */
662 public ChunkGenerator getGenerator();
663
664 /**
665 * Saves world to disk
666 */
667 public void save();
668
669 /**
670 * Gets a list of all applied {@link BlockPopulator}s for this World
671 *
672 * @return List containing any or none BlockPopulators
673 */
674 public List<BlockPopulator> getPopulators();
675
676 /**
677 * Spawn an entity of a specific class at the given {@link Location}
678 *
679 * @param location the {@link Location} to spawn the entity at
680 * @param clazz the class of the {@link Entity} to spawn
681 * @param <T> the class of the {@link Entity} to spawn
682 * @return an instance of the spawned {@link Entity}
683 * @throws IllegalArgumentException if either parameter is null or the
684 * {@link Entity} requested cannot be spawned
685 */
686 public <T extends Entity> T spawn(Location location, Class<T> clazz) throws IllegalArgumentException;
687
688 /**
689 * Spawn a {@link FallingBlock} entity at the given {@link Location} of
690 * the specified {@link Material}. The material dictates what is falling.
691 * When the FallingBlock hits the ground, it will place that block.
692 * <p>
693 * The Material must be a block type, check with {@link Material#isBlock()
694 * material.isBlock()}. The Material may not be air.
695 *
696 * @param location The {@link Location} to spawn the FallingBlock
697 * @param material The block {@link Material} type
698 * @param data The block data
699 * @return The spawned {@link FallingBlock} instance
700 * @throws IllegalArgumentException if {@link Location} or {@link
701 * Material} are null or {@link Material} is not a block
702 * @deprecated Magic value
703 */
704 @Deprecated
705 public FallingBlock spawnFallingBlock(Location location, Material material, byte data) throws IllegalArgumentException;
706
707 /**
708 * Spawn a {@link FallingBlock} entity at the given {@link Location} of
709 * the specified blockId (converted to {@link Material})
710 *
711 * @param location The {@link Location} to spawn the FallingBlock
712 * @param blockId The id of the intended material
713 * @param blockData The block data
714 * @return The spawned FallingBlock instance
715 * @throws IllegalArgumentException if location is null, or blockId is
716 * invalid
717 * @see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte)
718 * @deprecated Magic value
719 */
720 @Deprecated
721 public FallingBlock spawnFallingBlock(Location location, int blockId, byte blockData) throws IllegalArgumentException;
722
723 /**
724 * Plays an effect to all players within a default radius around a given
725 * location.
726 *
727 * @param location the {@link Location} around which players must be to
728 * hear the sound
729 * @param effect the {@link Effect}
730 * @param data a data bit needed for some effects
731 */
732 public void playEffect(Location location, Effect effect, int data);
733
734 /**
735 * Plays an effect to all players within a given radius around a location.
736 *
737 * @param location the {@link Location} around which players must be to
738 * hear the effect
739 * @param effect the {@link Effect}
740 * @param data a data bit needed for some effects
741 * @param radius the radius around the location
742 */
743 public void playEffect(Location location, Effect effect, int data, int radius);
744
745 /**
746 * Plays an effect to all players within a default radius around a given
747 * location.
748 *
749 * @param location the {@link Location} around which players must be to
750 * hear the sound
751 * @param effect the {@link Effect}
752 * @param data a data bit needed for some effects
753 */
754 public <T> void playEffect(Location location, Effect effect, T data);
755
756 /**
757 * Plays an effect to all players within a given radius around a location.
758 *
759 * @param location the {@link Location} around which players must be to
760 * hear the effect
761 * @param effect the {@link Effect}
762 * @param data a data bit needed for some effects
763 * @param radius the radius around the location
764 */
765 public <T> void playEffect(Location location, Effect effect, T data, int radius);
766
767 /**
768 * Get empty chunk snapshot (equivalent to all air blocks), optionally
769 * including valid biome data. Used for representing an ungenerated chunk,
770 * or for fetching only biome data without loading a chunk.
771 *
772 * @param x - chunk x coordinate
773 * @param z - chunk z coordinate
774 * @param includeBiome - if true, snapshot includes per-coordinate biome
775 * type
776 * @param includeBiomeTempRain - if true, snapshot includes per-coordinate
777 * raw biome temperature and rainfall
778 * @return The empty snapshot.
779 */
780 public ChunkSnapshot getEmptyChunkSnapshot(int x, int z, boolean includeBiome, boolean includeBiomeTempRain);
781
782 /**
783 * Sets the spawn flags for this.
784 *
785 * @param allowMonsters - if true, monsters are allowed to spawn in this
786 * world.
787 * @param allowAnimals - if true, animals are allowed to spawn in this
788 * world.
789 */
790 public void setSpawnFlags(boolean allowMonsters, boolean allowAnimals);
791
792 /**
793 * Gets whether animals can spawn in this world.
794 *
795 * @return whether animals can spawn in this world.
796 */
797 public boolean getAllowAnimals();
798
799 /**
800 * Gets whether monsters can spawn in this world.
801 *
802 * @return whether monsters can spawn in this world.
803 */
804 public boolean getAllowMonsters();
805
806 /**
807 * Gets the biome for the given block coordinates.
808 *
809 * @param x X coordinate of the block
810 * @param z Z coordinate of the block
811 * @return Biome of the requested block
812 */
813 Biome getBiome(int x, int z);
814
815 /**
816 * Sets the biome for the given block coordinates
817 *
818 * @param x X coordinate of the block
819 * @param z Z coordinate of the block
820 * @param bio new Biome type for this block
821 */
822 void setBiome(int x, int z, Biome bio);
823
824 /**
825 * Gets the temperature for the given block coordinates.
826 * <p>
827 * It is safe to run this method when the block does not exist, it will
828 * not create the block.
829 *
830 * @param x X coordinate of the block
831 * @param z Z coordinate of the block
832 * @return Temperature of the requested block
833 */
834 public double getTemperature(int x, int z);
835
836 /**
837 * Gets the humidity for the given block coordinates.
838 * <p>
839 * It is safe to run this method when the block does not exist, it will
840 * not create the block.
841 *
842 * @param x X coordinate of the block
843 * @param z Z coordinate of the block
844 * @return Humidity of the requested block
845 */
846 public double getHumidity(int x, int z);
847
848 /**
849 * Gets the maximum height of this world.
850 * <p>
851 * If the max height is 100, there are only blocks from y=0 to y=99.
852 *
853 * @return Maximum height of the world
854 */
855 public int getMaxHeight();
856
857 /**
858 * Gets the sea level for this world.
859 * <p>
860 * This is often half of {@link #getMaxHeight()}
861 *
862 * @return Sea level
863 */
864 public int getSeaLevel();
865
866 /**
867 * Gets whether the world's spawn area should be kept loaded into memory
868 * or not.
869 *
870 * @return true if the world's spawn area will be kept loaded into memory.
871 */
872 public boolean getKeepSpawnInMemory();
873
874 /**
875 * Sets whether the world's spawn area should be kept loaded into memory
876 * or not.
877 *
878 * @param keepLoaded if true then the world's spawn area will be kept
879 * loaded into memory.
880 */
881 public void setKeepSpawnInMemory(boolean keepLoaded);
882
883 /**
884 * Gets whether or not the world will automatically save
885 *
886 * @return true if the world will automatically save, otherwise false
887 */
888 public boolean isAutoSave();
889
890 /**
891 * Sets whether or not the world will automatically save
892 *
893 * @param value true if the world should automatically save, otherwise
894 * false
895 */
896 public void setAutoSave(boolean value);
897
898 /**
899 * Sets the Difficulty of the world.
900 *
901 * @param difficulty the new difficulty you want to set the world to
902 */
903 public void setDifficulty(Difficulty difficulty);
904
905 /**
906 * Gets the Difficulty of the world.
907 *
908 * @return The difficulty of the world.
909 */
910 public Difficulty getDifficulty();
911
912 /**
913 * Gets the folder of this world on disk.
914 *
915 * @return The folder of this world.
916 */
917 public File getWorldFolder();
918
919 /**
920 * Gets the type of this world.
921 *
922 * @return Type of this world.
923 */
924 public WorldType getWorldType();
925
926 /**
927 * Gets whether or not structures are being generated.
928 *
929 * @return True if structures are being generated.
930 */
931 public boolean canGenerateStructures();
932
933 /**
934 * Gets the world's ticks per animal spawns value
935 * <p>
936 * This value determines how many ticks there are between attempts to
937 * spawn animals.
938 * <p>
939 * <b>Example Usage:</b>
940 * <ul>
941 * <li>A value of 1 will mean the server will attempt to spawn animals in
942 * this world every tick.
943 * <li>A value of 400 will mean the server will attempt to spawn animals
944 * in this world every 400th tick.
945 * <li>A value below 0 will be reset back to Minecraft's default.
946 * </ul>
947 * <p>
948 * <b>Note:</b>
949 * If set to 0, animal spawning will be disabled for this world. We
950 * recommend using {@link #setSpawnFlags(boolean, boolean)} to control
951 * this instead.
952 * <p>
953 * Minecraft default: 400.
954 *
955 * @return The world's ticks per animal spawns value
956 */
957 public long getTicksPerAnimalSpawns();
958
959 /**
960 * Sets the world's ticks per animal spawns value
961 * <p>
962 * This value determines how many ticks there are between attempts to
963 * spawn animals.
964 * <p>
965 * <b>Example Usage:</b>
966 * <ul>
967 * <li>A value of 1 will mean the server will attempt to spawn animals in
968 * this world every tick.
969 * <li>A value of 400 will mean the server will attempt to spawn animals
970 * in this world every 400th tick.
971 * <li>A value below 0 will be reset back to Minecraft's default.
972 * </ul>
973 * <p>
974 * <b>Note:</b>
975 * If set to 0, animal spawning will be disabled for this world. We
976 * recommend using {@link #setSpawnFlags(boolean, boolean)} to control
977 * this instead.
978 * <p>
979 * Minecraft default: 400.
980 *
981 * @param ticksPerAnimalSpawns the ticks per animal spawns value you want
982 * to set the world to
983 */
984 public void setTicksPerAnimalSpawns(int ticksPerAnimalSpawns);
985
986 /**
987 * Gets the world's ticks per monster spawns value
988 * <p>
989 * This value determines how many ticks there are between attempts to
990 * spawn monsters.
991 * <p>
992 * <b>Example Usage:</b>
993 * <ul>
994 * <li>A value of 1 will mean the server will attempt to spawn monsters in
995 * this world every tick.
996 * <li>A value of 400 will mean the server will attempt to spawn monsters
997 * in this world every 400th tick.
998 * <li>A value below 0 will be reset back to Minecraft's default.
999 * </ul>
1000 * <p>
1001 * <b>Note:</b>
1002 * If set to 0, monsters spawning will be disabled for this world. We
1003 * recommend using {@link #setSpawnFlags(boolean, boolean)} to control
1004 * this instead.
1005 * <p>
1006 * Minecraft default: 1.
1007 *
1008 * @return The world's ticks per monster spawns value
1009 */
1010 public long getTicksPerMonsterSpawns();
1011
1012 /**
1013 * Sets the world's ticks per monster spawns value
1014 * <p>
1015 * This value determines how many ticks there are between attempts to
1016 * spawn monsters.
1017 * <p>
1018 * <b>Example Usage:</b>
1019 * <ul>
1020 * <li>A value of 1 will mean the server will attempt to spawn monsters in
1021 * this world on every tick.
1022 * <li>A value of 400 will mean the server will attempt to spawn monsters
1023 * in this world every 400th tick.
1024 * <li>A value below 0 will be reset back to Minecraft's default.
1025 * </ul>
1026 * <p>
1027 * <b>Note:</b>
1028 * If set to 0, monsters spawning will be disabled for this world. We
1029 * recommend using {@link #setSpawnFlags(boolean, boolean)} to control
1030 * this instead.
1031 * <p>
1032 * Minecraft default: 1.
1033 *
1034 * @param ticksPerMonsterSpawns the ticks per monster spawns value you
1035 * want to set the world to
1036 */
1037 public void setTicksPerMonsterSpawns(int ticksPerMonsterSpawns);
1038
1039 /**
1040 * Gets limit for number of monsters that can spawn in a chunk in this
1041 * world
1042 *
1043 * @return The monster spawn limit
1044 */
1045 int getMonsterSpawnLimit();
1046
1047 /**
1048 * Sets the limit for number of monsters that can spawn in a chunk in this
1049 * world
1050 * <p>
1051 * <b>Note:</b> If set to a negative number the world will use the
1052 * server-wide spawn limit instead.
1053 */
1054 void setMonsterSpawnLimit(int limit);
1055
1056 /**
1057 * Gets the limit for number of animals that can spawn in a chunk in this
1058 * world
1059 *
1060 * @return The animal spawn limit
1061 */
1062 int getAnimalSpawnLimit();
1063
1064 /**
1065 * Sets the limit for number of animals that can spawn in a chunk in this
1066 * world
1067 * <p>
1068 * <b>Note:</b> If set to a negative number the world will use the
1069 * server-wide spawn limit instead.
1070 */
1071 void setAnimalSpawnLimit(int limit);
1072
1073 /**
1074 * Gets the limit for number of water animals that can spawn in a chunk in
1075 * this world
1076 *
1077 * @return The water animal spawn limit
1078 */
1079 int getWaterAnimalSpawnLimit();
1080
1081 /**
1082 * Sets the limit for number of water animals that can spawn in a chunk in
1083 * this world
1084 * <p>
1085 * <b>Note:</b> If set to a negative number the world will use the
1086 * server-wide spawn limit instead.
1087 */
1088 void setWaterAnimalSpawnLimit(int limit);
1089
1090 /**
1091 * Gets the limit for number of ambient mobs that can spawn in a chunk in
1092 * this world
1093 *
1094 * @return The ambient spawn limit
1095 */
1096 int getAmbientSpawnLimit();
1097
1098 /**
1099 * Sets the limit for number of ambient mobs that can spawn in a chunk in
1100 * this world
1101 * <p>
1102 * <b>Note:</b> If set to a negative number the world will use the
1103 * server-wide spawn limit instead.
1104 */
1105 void setAmbientSpawnLimit(int limit);
1106
1107 /**
1108 * Play a Sound at the provided Location in the World
1109 * <p>
1110 * This function will fail silently if Location or Sound are null.
1111 *
1112 * @param location The location to play the sound
1113 * @param sound The sound to play
1114 * @param volume The volume of the sound
1115 * @param pitch The pitch of the sound
1116 */
1117 void playSound(Location location, Sound sound, float volume, float pitch);
1118
1119 /**
1120 * Get existing rules
1121 *
1122 * @return An array of rules
1123 */
1124 public String[] getGameRules();
1125
1126 /**
1127 * Gets the current state of the specified rule
1128 * <p>
1129 * Will return null if rule passed is null
1130 *
1131 * @param rule Rule to look up value of
1132 * @return String value of rule
1133 */
1134 public String getGameRuleValue(String rule);
1135
1136 /**
1137 * Set the specified gamerule to specified value.
1138 * <p>
1139 * The rule may attempt to validate the value passed, will return true if
1140 * value was set.
1141 * <p>
1142 * If rule is null, the function will return false.
1143 *
1144 * @param rule Rule to set
1145 * @param value Value to set rule to
1146 * @return True if rule was set
1147 */
1148 public boolean setGameRuleValue(String rule, String value);
1149
1150 /**
1151 * Checks if string is a valid game rule
1152 *
1153 * @param rule Rule to check
1154 * @return True if rule exists
1155 */
1156 public boolean isGameRule(String rule);
1157
1158 /**
1159 * Represents various map environment types that a world may be
1160 */
1161 public enum Environment {
1162
1163 /**
1164 * Represents the "normal"/"surface world" map
1165 */
1166 NORMAL(0),
1167 /**
1168 * Represents a nether based map ("hell")
1169 */
1170 NETHER(-1),
1171 /**
1172 * Represents the "end" map
1173 */
1174 THE_END(1);
1175
1176 private final int id;
1177 private static final Map<Integer, Environment> lookup = new HashMap<Integer, Environment>();
1178
1179 private Environment(int id) {
1180 this.id = id;
1181 }
1182
1183 /**
1184 * Gets the dimension ID of this environment
1185 *
1186 * @return dimension ID
1187 * @deprecated Magic value
1188 */
1189 @Deprecated
1190 public int getId() {
1191 return id;
1192 }
1193
1194 /**
1195 * Get an environment by ID
1196 *
1197 * @param id The ID of the environment
1198 * @return The environment
1199 * @deprecated Magic value
1200 */
1201 @Deprecated
1202 public static Environment getEnvironment(int id) {
1203 return lookup.get(id);
1204 }
1205
1206 static {
1207 for (Environment env : values()) {
1208 lookup.put(env.getId(), env);
1209 }
1210 }
1211 }
1212 }