Package org.bukkit

Interface World

All Superinterfaces:
Metadatable, PluginMessageRecipient

public interface World extends PluginMessageRecipient, Metadatable
Represents a world, which may contain entities, chunks and blocks
  • Method Details

    • getBlockAt

      @NotNull Block getBlockAt(int x, int y, int z)
      Gets the Block at the given coordinates
      Parameters:
      x - X-coordinate of the block
      y - Y-coordinate of the block
      z - Z-coordinate of the block
      Returns:
      Block at the given coordinates
    • getBlockAt

      @NotNull Block getBlockAt(@NotNull Location location)
      Gets the Block at the given Location
      Parameters:
      location - Location of the block
      Returns:
      Block at the given location
    • getHighestBlockYAt

      int getHighestBlockYAt(int x, int z)
      Gets the highest non-empty (impassable) coordinate at the given coordinates.
      Parameters:
      x - X-coordinate of the blocks
      z - Z-coordinate of the blocks
      Returns:
      Y-coordinate of the highest non-empty block
    • getHighestBlockYAt

      int getHighestBlockYAt(@NotNull Location location)
      Gets the highest non-empty (impassable) coordinate at the given Location.
      Parameters:
      location - Location of the blocks
      Returns:
      Y-coordinate of the highest non-empty block
    • getHighestBlockAt

      @NotNull Block getHighestBlockAt(int x, int z)
      Gets the highest non-empty (impassable) block at the given coordinates.
      Parameters:
      x - X-coordinate of the block
      z - Z-coordinate of the block
      Returns:
      Highest non-empty block
    • getHighestBlockAt

      @NotNull Block getHighestBlockAt(@NotNull Location location)
      Gets the highest non-empty (impassable) block at the given coordinates.
      Parameters:
      location - Coordinates to get the highest block
      Returns:
      Highest non-empty block
    • getHighestBlockYAt

      int getHighestBlockYAt(int x, int z, @NotNull HeightMap heightMap)
      Gets the highest coordinate corresponding to the HeightMap at the given coordinates.
      Parameters:
      x - X-coordinate of the blocks
      z - Z-coordinate of the blocks
      heightMap - the heightMap that is used to determine the highest point
      Returns:
      Y-coordinate of the highest block corresponding to the HeightMap
    • getHighestBlockYAt

      int getHighestBlockYAt(@NotNull Location location, @NotNull HeightMap heightMap)
      Gets the highest coordinate corresponding to the HeightMap at the given Location.
      Parameters:
      location - Location of the blocks
      heightMap - the heightMap that is used to determine the highest point
      Returns:
      Y-coordinate of the highest block corresponding to the HeightMap
    • getHighestBlockAt

      @NotNull Block getHighestBlockAt(int x, int z, @NotNull HeightMap heightMap)
      Gets the highest block corresponding to the HeightMap at the given coordinates.
      Parameters:
      x - X-coordinate of the block
      z - Z-coordinate of the block
      heightMap - the heightMap that is used to determine the highest point
      Returns:
      Highest block corresponding to the HeightMap
    • getHighestBlockAt

      @NotNull Block getHighestBlockAt(@NotNull Location location, @NotNull HeightMap heightMap)
      Gets the highest block corresponding to the HeightMap at the given coordinates.
      Parameters:
      location - Coordinates to get the highest block
      heightMap - the heightMap that is used to determine the highest point
      Returns:
      Highest block corresponding to the HeightMap
    • getChunkAt

      @NotNull Chunk getChunkAt(int x, int z)
      Gets the Chunk at the given coordinates
      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      Chunk at the given coordinates
    • getChunkAt

      @NotNull Chunk getChunkAt(@NotNull Location location)
      Gets the Chunk at the given Location
      Parameters:
      location - Location of the chunk
      Returns:
      Chunk at the given location
    • getChunkAt

      @NotNull Chunk getChunkAt(@NotNull Block block)
      Gets the Chunk that contains the given Block
      Parameters:
      block - Block to get the containing chunk from
      Returns:
      The chunk that contains the given block
    • isChunkLoaded

      boolean isChunkLoaded(@NotNull Chunk chunk)
      Checks if the specified Chunk is loaded
      Parameters:
      chunk - The chunk to check
      Returns:
      true if the chunk is loaded, otherwise false
    • getLoadedChunks

      @NotNull Chunk[] getLoadedChunks()
      Gets an array of all loaded Chunks
      Returns:
      Chunk[] containing all loaded chunks
    • loadChunk

      void loadChunk(@NotNull Chunk chunk)
      Loads the specified Chunk.

      This method will keep the specified chunk loaded until one of the unload methods is manually called. Callers are advised to instead use getChunkAt which will only temporarily load the requested chunk.

      Parameters:
      chunk - The chunk to load
    • isChunkLoaded

      boolean isChunkLoaded(int x, int z)
      Checks if the Chunk at the specified coordinates is loaded
      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      true if the chunk is loaded, otherwise false
    • isChunkGenerated

      boolean isChunkGenerated(int x, int z)
      Checks if the Chunk at the specified coordinates is generated
      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      true if the chunk is generated, otherwise false
    • isChunkInUse

      @Deprecated boolean isChunkInUse(int x, int z)
      Deprecated.
      This method was added to facilitate chunk garbage collection. As of the current Minecraft version chunks are now strictly managed and will not be loaded for more than 1 tick unless they are in use.
      Checks if the Chunk at the specified coordinates is loaded and in use by one or more players
      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      true if the chunk is loaded and in use by one or more players, otherwise false
    • loadChunk

      void loadChunk(int x, int z)
      Loads the Chunk at the specified coordinates.

      This method will keep the specified chunk loaded until one of the unload methods is manually called. Callers are advised to instead use getChunkAt which will only temporarily load the requested chunk.

      If the chunk does not exist, it will be generated.

      This method is analogous to loadChunk(int, int, boolean) where generate is true.

      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
    • loadChunk

      boolean loadChunk(int x, int z, boolean generate)
      Loads the Chunk at the specified coordinates.

      This method will keep the specified chunk loaded until one of the unload methods is manually called. Callers are advised to instead use getChunkAt which will only temporarily load the requested chunk.

      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      generate - Whether or not to generate a chunk if it doesn't already exist
      Returns:
      true if the chunk has loaded successfully, otherwise false
    • unloadChunk

      boolean unloadChunk(@NotNull Chunk chunk)
      Safely unloads and saves the Chunk at the specified coordinates

      This method is analogous to unloadChunk(int, int, boolean) where save is true.

      Parameters:
      chunk - the chunk to unload
      Returns:
      true if the chunk has unloaded successfully, otherwise false
    • unloadChunk

      boolean unloadChunk(int x, int z)
      Safely unloads and saves the Chunk at the specified coordinates

      This method is analogous to unloadChunk(int, int, boolean) where save is true.

      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      true if the chunk has unloaded successfully, otherwise false
    • unloadChunk

      boolean unloadChunk(int x, int z, boolean save)
      Safely unloads and optionally saves the Chunk at the specified coordinates.
      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      save - Whether or not to save the chunk
      Returns:
      true if the chunk has unloaded successfully, otherwise false
    • unloadChunkRequest

      boolean unloadChunkRequest(int x, int z)
      Safely queues the Chunk at the specified coordinates for unloading.
      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      true is the queue attempt was successful, otherwise false
    • regenerateChunk

      @Deprecated boolean regenerateChunk(int x, int z)
      Deprecated.
      regenerating a single chunk is not likely to produce the same chunk as before as terrain decoration may be spread across chunks. Use of this method should be avoided as it is known to produce buggy results.
      Regenerates the Chunk at the specified coordinates
      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      Whether the chunk was actually regenerated
    • refreshChunk

      @Deprecated boolean refreshChunk(int x, int z)
      Deprecated.
      This method is not guaranteed to work suitably across all client implementations.
      Resends the Chunk to all clients
      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      Whether the chunk was actually refreshed
    • isChunkForceLoaded

      boolean isChunkForceLoaded(int x, int z)
      Gets whether the chunk at the specified chunk coordinates is force loaded.

      A force loaded chunk will not be unloaded due to lack of player activity.

      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      force load status
    • setChunkForceLoaded

      void setChunkForceLoaded(int x, int z, boolean forced)
      Sets whether the chunk at the specified chunk coordinates is force loaded.

      A force loaded chunk will not be unloaded due to lack of player activity.

      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      forced - force load status
    • getForceLoadedChunks

      @NotNull Collection<Chunk> getForceLoadedChunks()
      Returns all force loaded chunks in this world.

      A force loaded chunk will not be unloaded due to lack of player activity.

      Returns:
      unmodifiable collection of force loaded chunks
    • addPluginChunkTicket

      boolean addPluginChunkTicket(int x, int z, @NotNull Plugin plugin)
      Adds a plugin ticket for the specified chunk, loading the chunk if it is not already loaded.

      A plugin ticket will prevent a chunk from unloading until it is explicitly removed. A plugin instance may only have one ticket per chunk, but each chunk can have multiple plugin tickets.

      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      plugin - Plugin which owns the ticket
      Returns:
      true if a plugin ticket was added, false if the ticket already exists for the plugin
      Throws:
      IllegalStateException - If the specified plugin is not enabled
      See Also:
      removePluginChunkTicket(int, int, Plugin)
    • removePluginChunkTicket

      boolean removePluginChunkTicket(int x, int z, @NotNull Plugin plugin)
      Removes the specified plugin's ticket for the specified chunk

      A plugin ticket will prevent a chunk from unloading until it is explicitly removed. A plugin instance may only have one ticket per chunk, but each chunk can have multiple plugin tickets.

      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      plugin - Plugin which owns the ticket
      Returns:
      true if the plugin ticket was removed, false if there is no plugin ticket for the chunk
      See Also:
      addPluginChunkTicket(int, int, Plugin)
    • removePluginChunkTickets

      void removePluginChunkTickets(@NotNull Plugin plugin)
      Removes all plugin tickets for the specified plugin

      A plugin ticket will prevent a chunk from unloading until it is explicitly removed. A plugin instance may only have one ticket per chunk, but each chunk can have multiple plugin tickets.

      Parameters:
      plugin - Specified plugin
      See Also:
      addPluginChunkTicket(int, int, Plugin), removePluginChunkTicket(int, int, Plugin)
    • getPluginChunkTickets

      @NotNull Collection<Plugin> getPluginChunkTickets(int x, int z)
      Retrieves a collection specifying which plugins have tickets for the specified chunk. This collection is not updated when plugin tickets are added or removed to the chunk.

      A plugin ticket will prevent a chunk from unloading until it is explicitly removed. A plugin instance may only have one ticket per chunk, but each chunk can have multiple plugin tickets.

      Parameters:
      x - X-coordinate of the chunk
      z - Z-coordinate of the chunk
      Returns:
      unmodifiable collection containing which plugins have tickets for the chunk
      See Also:
      addPluginChunkTicket(int, int, Plugin), removePluginChunkTicket(int, int, Plugin)
    • getPluginChunkTickets

      @NotNull Map<Plugin,​Collection<Chunk>> getPluginChunkTickets()
      Returns a map of which plugins have tickets for what chunks. The returned map is not updated when plugin tickets are added or removed to chunks. If a plugin has no tickets, it will be absent from the map.

      A plugin ticket will prevent a chunk from unloading until it is explicitly removed. A plugin instance may only have one ticket per chunk, but each chunk can have multiple plugin tickets.

      Returns:
      unmodifiable map containing which plugins have tickets for what chunks
      See Also:
      addPluginChunkTicket(int, int, Plugin), removePluginChunkTicket(int, int, Plugin)
    • dropItem

      @NotNull Item dropItem(@NotNull Location location, @NotNull ItemStack item)
      Drops an item at the specified Location
      Parameters:
      location - Location to drop the item
      item - ItemStack to drop
      Returns:
      ItemDrop entity created as a result of this method
    • dropItem

      @NotNull Item dropItem(@NotNull Location location, @NotNull ItemStack item, @Nullable Consumer<Item> function)
      Drops an item at the specified Location Note that functions will run before the entity is spawned
      Parameters:
      location - Location to drop the item
      item - ItemStack to drop
      function - the function to be run before the entity is spawned.
      Returns:
      ItemDrop entity created as a result of this method
    • dropItemNaturally

      @NotNull Item dropItemNaturally(@NotNull Location location, @NotNull ItemStack item)
      Drops an item at the specified Location with a random offset
      Parameters:
      location - Location to drop the item
      item - ItemStack to drop
      Returns:
      ItemDrop entity created as a result of this method
    • dropItemNaturally

      @NotNull Item dropItemNaturally(@NotNull Location location, @NotNull ItemStack item, @Nullable Consumer<Item> function)
      Drops an item at the specified Location with a random offset Note that functions will run before the entity is spawned
      Parameters:
      location - Location to drop the item
      item - ItemStack to drop
      function - the function to be run before the entity is spawned.
      Returns:
      ItemDrop entity created as a result of this method
    • spawnArrow

      @NotNull Arrow spawnArrow(@NotNull Location location, @NotNull Vector direction, float speed, float spread)
      Creates an Arrow entity at the given Location
      Parameters:
      location - Location to spawn the arrow
      direction - Direction to shoot the arrow in
      speed - Speed of the arrow. A recommend speed is 0.6
      spread - Spread of the arrow. A recommend spread is 12
      Returns:
      Arrow entity spawned as a result of this method
    • spawnArrow

      @NotNull <T extends AbstractArrow> T spawnArrow(@NotNull Location location, @NotNull Vector direction, float speed, float spread, @NotNull Class<T> clazz)
      Creates an arrow entity of the given class at the given Location
      Type Parameters:
      T - type of arrow to spawn
      Parameters:
      location - Location to spawn the arrow
      direction - Direction to shoot the arrow in
      speed - Speed of the arrow. A recommend speed is 0.6
      spread - Spread of the arrow. A recommend spread is 12
      clazz - the Entity class for the arrow SpectralArrow,Arrow,TippedArrow
      Returns:
      Arrow entity spawned as a result of this method
    • generateTree

      boolean generateTree(@NotNull Location location, @NotNull TreeType type)
      Creates a tree at the given Location
      Parameters:
      location - Location to spawn the tree
      type - Type of the tree to create
      Returns:
      true if the tree was created successfully, otherwise false
    • generateTree

      boolean generateTree(@NotNull Location loc, @NotNull TreeType type, @NotNull BlockChangeDelegate delegate)
      Creates a tree at the given Location
      Parameters:
      loc - Location to spawn the tree
      type - Type of the tree to create
      delegate - A class to call for each block changed as a result of this method
      Returns:
      true if the tree was created successfully, otherwise false
    • spawnEntity

      @NotNull Entity spawnEntity(@NotNull Location loc, @NotNull EntityType type)
      Creates a entity at the given Location
      Parameters:
      loc - The location to spawn the entity
      type - The entity to spawn
      Returns:
      Resulting Entity of this method
    • strikeLightning

      @NotNull LightningStrike strikeLightning(@NotNull Location loc)
      Strikes lightning at the given Location
      Parameters:
      loc - The location to strike lightning
      Returns:
      The lightning entity.
    • strikeLightningEffect

      @NotNull LightningStrike strikeLightningEffect(@NotNull Location loc)
      Strikes lightning at the given Location without doing damage
      Parameters:
      loc - The location to strike lightning
      Returns:
      The lightning entity.
    • getEntities

      @NotNull List<Entity> getEntities()
      Get a list of all entities in this World
      Returns:
      A List of all Entities currently residing in this world
    • getLivingEntities

      @NotNull List<LivingEntity> getLivingEntities()
      Get a list of all living entities in this World
      Returns:
      A List of all LivingEntities currently residing in this world
    • getEntitiesByClass

      @Deprecated @NotNull <T extends Entity> Collection<T> getEntitiesByClass(@NotNull Class<T>... classes)
      Deprecated.
      Get a collection of all entities in this World matching the given class/interface
      Type Parameters:
      T - an entity subclass
      Parameters:
      classes - The classes representing the types of entity to match
      Returns:
      A List of all Entities currently residing in this world that match the given class/interface
    • getEntitiesByClass

      @NotNull <T extends Entity> Collection<T> getEntitiesByClass(@NotNull Class<T> cls)
      Get a collection of all entities in this World matching the given class/interface
      Type Parameters:
      T - an entity subclass
      Parameters:
      cls - The class representing the type of entity to match
      Returns:
      A List of all Entities currently residing in this world that match the given class/interface
    • getEntitiesByClasses

      @NotNull Collection<Entity> getEntitiesByClasses(@NotNull Class<?>... classes)
      Get a collection of all entities in this World matching any of the given classes/interfaces
      Parameters:
      classes - The classes representing the types of entity to match
      Returns:
      A List of all Entities currently residing in this world that match one or more of the given classes/interfaces
    • getPlayers

      @NotNull List<Player> getPlayers()
      Get a list of all players in this World
      Returns:
      A list of all Players currently residing in this world
    • getNearbyEntities

      @NotNull Collection<Entity> getNearbyEntities(@NotNull Location location, double x, double y, double z)
      Returns a list of entities within a bounding box centered around a Location.

      This may not consider entities in currently unloaded chunks. Some implementations may impose artificial restrictions on the size of the search bounding box.

      Parameters:
      location - The center of the bounding box
      x - 1/2 the size of the box along x axis
      y - 1/2 the size of the box along y axis
      z - 1/2 the size of the box along z axis
      Returns:
      the collection of entities near location. This will always be a non-null collection.
    • getNearbyEntities

      @NotNull Collection<Entity> getNearbyEntities(@NotNull Location location, double x, double y, double z, @Nullable Predicate<Entity> filter)
      Returns a list of entities within a bounding box centered around a Location.

      This may not consider entities in currently unloaded chunks. Some implementations may impose artificial restrictions on the size of the search bounding box.

      Parameters:
      location - The center of the bounding box
      x - 1/2 the size of the box along x axis
      y - 1/2 the size of the box along y axis
      z - 1/2 the size of the box along z axis
      filter - only entities that fulfill this predicate are considered, or null to consider all entities
      Returns:
      the collection of entities near location. This will always be a non-null collection.
    • getNearbyEntities

      @NotNull Collection<Entity> getNearbyEntities(@NotNull BoundingBox boundingBox)
      Returns a list of entities within the given bounding box.

      This may not consider entities in currently unloaded chunks. Some implementations may impose artificial restrictions on the size of the search bounding box.

      Parameters:
      boundingBox - the bounding box
      Returns:
      the collection of entities within the bounding box, will always be a non-null collection
    • getNearbyEntities

      @NotNull Collection<Entity> getNearbyEntities(@NotNull BoundingBox boundingBox, @Nullable Predicate<Entity> filter)
      Returns a list of entities within the given bounding box.

      This may not consider entities in currently unloaded chunks. Some implementations may impose artificial restrictions on the size of the search bounding box.

      Parameters:
      boundingBox - the bounding box
      filter - only entities that fulfill this predicate are considered, or null to consider all entities
      Returns:
      the collection of entities within the bounding box, will always be a non-null collection
    • rayTraceEntities

      @Nullable RayTraceResult rayTraceEntities(@NotNull Location start, @NotNull Vector direction, double maxDistance)
      Performs a ray trace that checks for entity collisions.

      This may not consider entities in currently unloaded chunks. Some implementations may impose artificial restrictions on the maximum distance.

      Parameters:
      start - the start position
      direction - the ray direction
      maxDistance - the maximum distance
      Returns:
      the closest ray trace hit result, or null if there is no hit
      See Also:
      rayTraceEntities(Location, Vector, double, double, Predicate)
    • rayTraceEntities

      @Nullable RayTraceResult rayTraceEntities(@NotNull Location start, @NotNull Vector direction, double maxDistance, double raySize)
      Performs a ray trace that checks for entity collisions.

      This may not consider entities in currently unloaded chunks. Some implementations may impose artificial restrictions on the maximum distance.

      Parameters:
      start - the start position
      direction - the ray direction
      maxDistance - the maximum distance
      raySize - entity bounding boxes will be uniformly expanded (or shrinked) by this value before doing collision checks
      Returns:
      the closest ray trace hit result, or null if there is no hit
      See Also:
      rayTraceEntities(Location, Vector, double, double, Predicate)
    • rayTraceEntities

      @Nullable RayTraceResult rayTraceEntities(@NotNull Location start, @NotNull Vector direction, double maxDistance, @Nullable Predicate<Entity> filter)
      Performs a ray trace that checks for entity collisions.

      This may not consider entities in currently unloaded chunks. Some implementations may impose artificial restrictions on the maximum distance.

      Parameters:
      start - the start position
      direction - the ray direction
      maxDistance - the maximum distance
      filter - only entities that fulfill this predicate are considered, or null to consider all entities
      Returns:
      the closest ray trace hit result, or null if there is no hit
      See Also:
      rayTraceEntities(Location, Vector, double, double, Predicate)
    • rayTraceEntities

      @Nullable RayTraceResult rayTraceEntities(@NotNull Location start, @NotNull Vector direction, double maxDistance, double raySize, @Nullable Predicate<Entity> filter)
      Performs a ray trace that checks for entity collisions.

      This may not consider entities in currently unloaded chunks. Some implementations may impose artificial restrictions on the maximum distance.

      Parameters:
      start - the start position
      direction - the ray direction
      maxDistance - the maximum distance
      raySize - entity bounding boxes will be uniformly expanded (or shrinked) by this value before doing collision checks
      filter - only entities that fulfill this predicate are considered, or null to consider all entities
      Returns:
      the closest ray trace hit result, or null if there is no hit
    • rayTraceBlocks

      @Nullable RayTraceResult rayTraceBlocks(@NotNull Location start, @NotNull Vector direction, double maxDistance)
      Performs a ray trace that checks for block collisions using the blocks' precise collision shapes.

      This takes collisions with passable blocks into account, but ignores fluids.

      This may cause loading of chunks! Some implementations may impose artificial restrictions on the maximum distance.

      Parameters:
      start - the start location
      direction - the ray direction
      maxDistance - the maximum distance
      Returns:
      the ray trace hit result, or null if there is no hit
      See Also:
      rayTraceBlocks(Location, Vector, double, FluidCollisionMode, boolean)
    • rayTraceBlocks

      @Nullable RayTraceResult rayTraceBlocks(@NotNull Location start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode)
      Performs a ray trace that checks for block collisions using the blocks' precise collision shapes.

      This takes collisions with passable blocks into account.

      This may cause loading of chunks! Some implementations may impose artificial restrictions on the maximum distance.

      Parameters:
      start - the start location
      direction - the ray direction
      maxDistance - the maximum distance
      fluidCollisionMode - the fluid collision mode
      Returns:
      the ray trace hit result, or null if there is no hit
      See Also:
      rayTraceBlocks(Location, Vector, double, FluidCollisionMode, boolean)
    • rayTraceBlocks

      @Nullable RayTraceResult rayTraceBlocks(@NotNull Location start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode, boolean ignorePassableBlocks)
      Performs a ray trace that checks for block collisions using the blocks' precise collision shapes.

      If collisions with passable blocks are ignored, fluid collisions are ignored as well regardless of the fluid collision mode.

      Portal blocks are only considered passable if the ray starts within them. Apart from that collisions with portal blocks will be considered even if collisions with passable blocks are otherwise ignored.

      This may cause loading of chunks! Some implementations may impose artificial restrictions on the maximum distance.

      Parameters:
      start - the start location
      direction - the ray direction
      maxDistance - the maximum distance
      fluidCollisionMode - the fluid collision mode
      ignorePassableBlocks - whether to ignore passable but collidable blocks (ex. tall grass, signs, fluids, ..)
      Returns:
      the ray trace hit result, or null if there is no hit
    • rayTrace

      @Nullable RayTraceResult rayTrace(@NotNull Location start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode, boolean ignorePassableBlocks, double raySize, @Nullable Predicate<Entity> filter)
      Performs a ray trace that checks for both block and entity collisions.

      Block collisions use the blocks' precise collision shapes. The raySize parameter is only taken into account for entity collision checks.

      If collisions with passable blocks are ignored, fluid collisions are ignored as well regardless of the fluid collision mode.

      Portal blocks are only considered passable if the ray starts within them. Apart from that collisions with portal blocks will be considered even if collisions with passable blocks are otherwise ignored.

      This may cause loading of chunks! Some implementations may impose artificial restrictions on the maximum distance.

      Parameters:
      start - the start location
      direction - the ray direction
      maxDistance - the maximum distance
      fluidCollisionMode - the fluid collision mode
      ignorePassableBlocks - whether to ignore passable but collidable blocks (ex. tall grass, signs, fluids, ..)
      raySize - entity bounding boxes will be uniformly expanded (or shrinked) by this value before doing collision checks
      filter - only entities that fulfill this predicate are considered, or null to consider all entities
      Returns:
      the closest ray trace hit result with either a block or an entity, or null if there is no hit
    • getName

      @NotNull String getName()
      Gets the unique name of this world
      Returns:
      Name of this world
    • getUID

      @NotNull UUID getUID()
      Gets the Unique ID of this world
      Returns:
      Unique ID of this world.
    • getSpawnLocation

      @NotNull Location getSpawnLocation()
      Gets the default spawn Location of this world
      Returns:
      The spawn location of this world
    • setSpawnLocation

      boolean setSpawnLocation(@NotNull Location location)
      Sets the spawn location of the world.
      The location provided must be equal to this world.
      Parameters:
      location - The Location to set the spawn for this world at.
      Returns:
      True if it was successfully set.
    • setSpawnLocation

      boolean setSpawnLocation(int x, int y, int z, float angle)
      Sets the spawn location of the world
      Parameters:
      x - X coordinate
      y - Y coordinate
      z - Z coordinate
      angle - the angle
      Returns:
      True if it was successfully set.
    • setSpawnLocation

      boolean setSpawnLocation(int x, int y, int z)
      Sets the spawn location of the world
      Parameters:
      x - X coordinate
      y - Y coordinate
      z - Z coordinate
      Returns:
      True if it was successfully set.
    • getTime

      long getTime()
      Gets the relative in-game time of this world.

      The relative time is analogous to hours * 1000

      Returns:
      The current relative time
      See Also:
      Returns an absolute time of this world
    • setTime

      void setTime(long time)
      Sets the relative in-game time on the server.

      The relative time is analogous to hours * 1000

      Note that setting the relative time below the current relative time will actually move the clock forward a day. If you require to rewind time, please see setFullTime(long)

      Parameters:
      time - The new relative time to set the in-game time to (in hours*1000)
      See Also:
      Sets the absolute time of this world
    • getFullTime

      long getFullTime()
      Gets the full in-game time on this world
      Returns:
      The current absolute time
      See Also:
      Returns a relative time of this world
    • setFullTime

      void setFullTime(long time)
      Sets the in-game time on the server

      Note that this sets the full time of the world, which may cause adverse effects such as breaking redstone clocks and any scheduled events

      Parameters:
      time - The new absolute time to set this world to
      See Also:
      Sets the relative time of this world
    • getGameTime

      long getGameTime()
      Gets the full in-game time on this world since the world generation
      Returns:
      The current absolute time since the world generation
      See Also:
      Returns a relative time of this world, Returns an absolute time of this world
    • hasStorm

      boolean hasStorm()
      Returns whether the world has an ongoing storm.
      Returns:
      Whether there is an ongoing storm
    • setStorm

      void setStorm(boolean hasStorm)
      Set whether there is a storm. A duration will be set for the new current conditions. This will implicitly call setClearWeatherDuration(int) with 0 ticks to reset the world's clear weather.
      Parameters:
      hasStorm - Whether there is rain and snow
    • getWeatherDuration

      int getWeatherDuration()
      Get the remaining time in ticks of the current conditions.
      Returns:
      Time in ticks
    • setWeatherDuration

      void setWeatherDuration(int duration)
      Set the remaining time in ticks of the current conditions.
      Parameters:
      duration - Time in ticks
    • isThundering

      boolean isThundering()
      Returns whether there is thunder.
      Returns:
      Whether there is thunder
    • setThundering

      void setThundering(boolean thundering)
      Set whether it is thundering. This will implicitly call setClearWeatherDuration(int) with 0 ticks to reset the world's clear weather.
      Parameters:
      thundering - Whether it is thundering
    • getThunderDuration

      int getThunderDuration()
      Get the thundering duration.
      Returns:
      Duration in ticks
    • setThunderDuration

      void setThunderDuration(int duration)
      Set the thundering duration.
      Parameters:
      duration - Duration in ticks
    • isClearWeather

      boolean isClearWeather()
      Returns whether the world has clear weather. This will be true such that isThundering() and hasStorm() are both false.
      Returns:
      true if clear weather
    • setClearWeatherDuration

      void setClearWeatherDuration(int duration)
      Set the clear weather duration. The clear weather ticks determine whether or not the world will be allowed to rain or storm. If clear weather ticks are > 0, the world will not naturally do either until the duration has elapsed. This method is equivalent to calling /weather clear with a set amount of ticks.
      Parameters:
      duration - duration in ticks
    • getClearWeatherDuration

      int getClearWeatherDuration()
      Get the clear weather duration.
      Returns:
      duration in ticks
    • createExplosion

      boolean createExplosion(double x, double y, double z, float power)
      Creates explosion at given coordinates with given power
      Parameters:
      x - X coordinate
      y - Y coordinate
      z - Z coordinate
      power - The power of explosion, where 4F is TNT
      Returns:
      false if explosion was canceled, otherwise true
    • createExplosion

      boolean createExplosion(double x, double y, double z, float power, boolean setFire)
      Creates explosion at given coordinates with given power and optionally setting blocks on fire.
      Parameters:
      x - X coordinate
      y - Y coordinate
      z - Z coordinate
      power - The power of explosion, where 4F is TNT
      setFire - Whether or not to set blocks on fire
      Returns:
      false if explosion was canceled, otherwise true
    • createExplosion

      boolean createExplosion(double x, double y, double z, float power, boolean setFire, boolean breakBlocks)
      Creates explosion at given coordinates with given power and optionally setting blocks on fire or breaking blocks.
      Parameters:
      x - X coordinate
      y - Y coordinate
      z - Z coordinate
      power - The power of explosion, where 4F is TNT
      setFire - Whether or not to set blocks on fire
      breakBlocks - Whether or not to have blocks be destroyed
      Returns:
      false if explosion was canceled, otherwise true
    • createExplosion

      boolean createExplosion(double x, double y, double z, float power, boolean setFire, boolean breakBlocks, @Nullable Entity source)
      Creates explosion at given coordinates with given power and optionally setting blocks on fire or breaking blocks.
      Parameters:
      x - X coordinate
      y - Y coordinate
      z - Z coordinate
      power - The power of explosion, where 4F is TNT
      setFire - Whether or not to set blocks on fire
      breakBlocks - Whether or not to have blocks be destroyed
      source - the source entity, used for tracking damage
      Returns:
      false if explosion was canceled, otherwise true
    • createExplosion

      boolean createExplosion(@NotNull Location loc, float power)
      Creates explosion at given coordinates with given power
      Parameters:
      loc - Location to blow up
      power - The power of explosion, where 4F is TNT
      Returns:
      false if explosion was canceled, otherwise true
    • createExplosion

      boolean createExplosion(@NotNull Location loc, float power, boolean setFire)
      Creates explosion at given coordinates with given power and optionally setting blocks on fire.
      Parameters:
      loc - Location to blow up
      power - The power of explosion, where 4F is TNT
      setFire - Whether or not to set blocks on fire
      Returns:
      false if explosion was canceled, otherwise true
    • createExplosion

      boolean createExplosion(@NotNull Location loc, float power, boolean setFire, boolean breakBlocks)
      Creates explosion at given coordinates with given power and optionally setting blocks on fire or breaking blocks.
      Parameters:
      loc - Location to blow up
      power - The power of explosion, where 4F is TNT
      setFire - Whether or not to set blocks on fire
      breakBlocks - Whether or not to have blocks be destroyed
      Returns:
      false if explosion was canceled, otherwise true
    • createExplosion

      boolean createExplosion(@NotNull Location loc, float power, boolean setFire, boolean breakBlocks, @Nullable Entity source)
      Creates explosion at given coordinates with given power and optionally setting blocks on fire or breaking blocks.
      Parameters:
      loc - Location to blow up
      power - The power of explosion, where 4F is TNT
      setFire - Whether or not to set blocks on fire
      breakBlocks - Whether or not to have blocks be destroyed
      source - the source entity, used for tracking damage
      Returns:
      false if explosion was canceled, otherwise true
    • getEnvironment

      @NotNull World.Environment getEnvironment()
      Gets the World.Environment type of this world
      Returns:
      This worlds Environment type
    • getSeed

      long getSeed()
      Gets the Seed for this world.
      Returns:
      This worlds Seed
    • getPVP

      boolean getPVP()
      Gets the current PVP setting for this world.
      Returns:
      True if PVP is enabled
    • setPVP

      void setPVP(boolean pvp)
      Sets the PVP setting for this world.
      Parameters:
      pvp - True/False whether PVP should be Enabled.
    • getGenerator

      @Nullable ChunkGenerator getGenerator()
      Gets the chunk generator for this world
      Returns:
      ChunkGenerator associated with this world
    • save

      void save()
      Saves world to disk
    • getPopulators

      @NotNull List<BlockPopulator> getPopulators()
      Gets a list of all applied BlockPopulators for this World
      Returns:
      List containing any or none BlockPopulators
    • spawn

      @NotNull <T extends Entity> T spawn(@NotNull Location location, @NotNull Class<T> clazz) throws IllegalArgumentException
      Spawn an entity of a specific class at the given Location
      Type Parameters:
      T - the class of the Entity to spawn
      Parameters:
      location - the Location to spawn the entity at
      clazz - the class of the Entity to spawn
      Returns:
      an instance of the spawned Entity
      Throws:
      IllegalArgumentException - if either parameter is null or the Entity requested cannot be spawned
    • spawn

      @NotNull <T extends Entity> T spawn(@NotNull Location location, @NotNull Class<T> clazz, @Nullable Consumer<T> function) throws IllegalArgumentException
      Spawn an entity of a specific class at the given Location, with the supplied function run before the entity is added to the world.
      Note that when the function is run, the entity will not be actually in the world. Any operation involving such as teleporting the entity is undefined until after this function returns.
      Type Parameters:
      T - the class of the Entity to spawn
      Parameters:
      location - the Location to spawn the entity at
      clazz - the class of the Entity to spawn
      function - the function to be run before the entity is spawned.
      Returns:
      an instance of the spawned Entity
      Throws:
      IllegalArgumentException - if either parameter is null or the Entity requested cannot be spawned
    • spawnFallingBlock

      Spawn a FallingBlock entity at the given Location of the specified Material. The material dictates what is falling. When the FallingBlock hits the ground, it will place that block.

      The Material must be a block type, check with material.isBlock(). The Material may not be air.

      Parameters:
      location - The Location to spawn the FallingBlock
      data - The block data
      Returns:
      The spawned FallingBlock instance
      Throws:
      IllegalArgumentException - if Location or MaterialData are null or Material of the MaterialData is not a block
    • spawnFallingBlock

      @NotNull FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull BlockData data) throws IllegalArgumentException
      Spawn a FallingBlock entity at the given Location of the specified Material. The material dictates what is falling. When the FallingBlock hits the ground, it will place that block.

      The Material must be a block type, check with material.isBlock(). The Material may not be air.

      Parameters:
      location - The Location to spawn the FallingBlock
      data - The block data
      Returns:
      The spawned FallingBlock instance
      Throws:
      IllegalArgumentException - if Location or BlockData are null
    • spawnFallingBlock

      @Deprecated @NotNull FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull Material material, byte data) throws IllegalArgumentException
      Deprecated.
      Magic value
      Spawn a FallingBlock entity at the given Location of the specified Material. The material dictates what is falling. When the FallingBlock hits the ground, it will place that block.

      The Material must be a block type, check with material.isBlock(). The Material may not be air.

      Parameters:
      location - The Location to spawn the FallingBlock
      material - The block Material type
      data - The block data
      Returns:
      The spawned FallingBlock instance
      Throws:
      IllegalArgumentException - if Location or Material are null or Material is not a block
    • playEffect

      void playEffect(@NotNull Location location, @NotNull Effect effect, int data)
      Plays an effect to all players within a default radius around a given location.
      Parameters:
      location - the Location around which players must be to hear the sound
      effect - the Effect
      data - a data bit needed for some effects
    • playEffect

      void playEffect(@NotNull Location location, @NotNull Effect effect, int data, int radius)
      Plays an effect to all players within a given radius around a location.
      Parameters:
      location - the Location around which players must be to hear the effect
      effect - the Effect
      data - a data bit needed for some effects
      radius - the radius around the location
    • playEffect

      <T> void playEffect(@NotNull Location location, @NotNull Effect effect, @Nullable T data)
      Plays an effect to all players within a default radius around a given location.
      Type Parameters:
      T - data dependant on the type of effect
      Parameters:
      location - the Location around which players must be to hear the sound
      effect - the Effect
      data - a data bit needed for some effects
    • playEffect

      <T> void playEffect(@NotNull Location location, @NotNull Effect effect, @Nullable T data, int radius)
      Plays an effect to all players within a given radius around a location.
      Type Parameters:
      T - data dependant on the type of effect
      Parameters:
      location - the Location around which players must be to hear the effect
      effect - the Effect
      data - a data bit needed for some effects
      radius - the radius around the location
    • getEmptyChunkSnapshot

      @NotNull ChunkSnapshot getEmptyChunkSnapshot(int x, int z, boolean includeBiome, boolean includeBiomeTemp)
      Get empty chunk snapshot (equivalent to all air blocks), optionally including valid biome data. Used for representing an ungenerated chunk, or for fetching only biome data without loading a chunk.
      Parameters:
      x - - chunk x coordinate
      z - - chunk z coordinate
      includeBiome - - if true, snapshot includes per-coordinate biome type
      includeBiomeTemp - - if true, snapshot includes per-coordinate raw biome temperature
      Returns:
      The empty snapshot.
    • setSpawnFlags

      void setSpawnFlags(boolean allowMonsters, boolean allowAnimals)
      Sets the spawn flags for this.
      Parameters:
      allowMonsters - - if true, monsters are allowed to spawn in this world.
      allowAnimals - - if true, animals are allowed to spawn in this world.
    • getAllowAnimals

      boolean getAllowAnimals()
      Gets whether animals can spawn in this world.
      Returns:
      whether animals can spawn in this world.
    • getAllowMonsters

      boolean getAllowMonsters()
      Gets whether monsters can spawn in this world.
      Returns:
      whether monsters can spawn in this world.
    • getBiome

      @NotNull @Deprecated Biome getBiome(int x, int z)
      Deprecated.
      biomes are now 3-dimensional
      Gets the biome for the given block coordinates.
      Parameters:
      x - X coordinate of the block
      z - Z coordinate of the block
      Returns:
      Biome of the requested block
    • getBiome

      @NotNull Biome getBiome(int x, int y, int z)
      Gets the biome for the given block coordinates.
      Parameters:
      x - X coordinate of the block
      y - Y coordinate of the block
      z - Z coordinate of the block
      Returns:
      Biome of the requested block
    • setBiome

      @Deprecated void setBiome(int x, int z, @NotNull Biome bio)
      Deprecated.
      biomes are now 3-dimensional
      Sets the biome for the given block coordinates
      Parameters:
      x - X coordinate of the block
      z - Z coordinate of the block
      bio - new Biome type for this block
    • setBiome

      void setBiome(int x, int y, int z, @NotNull Biome bio)
      Sets the biome for the given block coordinates
      Parameters:
      x - X coordinate of the block
      y - Y coordinate of the block
      z - Z coordinate of the block
      bio - new Biome type for this block
    • getTemperature

      @Deprecated double getTemperature(int x, int z)
      Deprecated.
      biomes are now 3-dimensional
      Gets the temperature for the given block coordinates.

      It is safe to run this method when the block does not exist, it will not create the block.

      This method will return the raw temperature without adjusting for block height effects.

      Parameters:
      x - X coordinate of the block
      z - Z coordinate of the block
      Returns:
      Temperature of the requested block
    • getTemperature

      double getTemperature(int x, int y, int z)
      Gets the temperature for the given block coordinates.

      It is safe to run this method when the block does not exist, it will not create the block.

      This method will return the raw temperature without adjusting for block height effects.

      Parameters:
      x - X coordinate of the block
      y - Y coordinate of the block
      z - Z coordinate of the block
      Returns:
      Temperature of the requested block
    • getHumidity

      @Deprecated double getHumidity(int x, int z)
      Deprecated.
      biomes are now 3-dimensional
      Gets the humidity for the given block coordinates.

      It is safe to run this method when the block does not exist, it will not create the block.

      Parameters:
      x - X coordinate of the block
      z - Z coordinate of the block
      Returns:
      Humidity of the requested block
    • getHumidity

      double getHumidity(int x, int y, int z)
      Gets the humidity for the given block coordinates.

      It is safe to run this method when the block does not exist, it will not create the block.

      Parameters:
      x - X coordinate of the block
      y - Y coordinate of the block
      z - Z coordinate of the block
      Returns:
      Humidity of the requested block
    • getMinHeight

      int getMinHeight()
      Gets the minimum height of this world.

      If the min height is 0, there are only blocks from y=0.

      Returns:
      Minimum height of the world
    • getMaxHeight

      int getMaxHeight()
      Gets the maximum height of this world.

      If the max height is 100, there are only blocks from y=0 to y=99.

      Returns:
      Maximum height of the world
    • getSeaLevel

      int getSeaLevel()
      Gets the sea level for this world.

      This is often half of getMaxHeight()

      Returns:
      Sea level
    • getKeepSpawnInMemory

      boolean getKeepSpawnInMemory()
      Gets whether the world's spawn area should be kept loaded into memory or not.
      Returns:
      true if the world's spawn area will be kept loaded into memory.
    • setKeepSpawnInMemory

      void setKeepSpawnInMemory(boolean keepLoaded)
      Sets whether the world's spawn area should be kept loaded into memory or not.
      Parameters:
      keepLoaded - if true then the world's spawn area will be kept loaded into memory.
    • isAutoSave

      boolean isAutoSave()
      Gets whether or not the world will automatically save
      Returns:
      true if the world will automatically save, otherwise false
    • setAutoSave

      void setAutoSave(boolean value)
      Sets whether or not the world will automatically save
      Parameters:
      value - true if the world should automatically save, otherwise false
    • setDifficulty

      void setDifficulty(@NotNull Difficulty difficulty)
      Sets the Difficulty of the world.
      Parameters:
      difficulty - the new difficulty you want to set the world to
    • getDifficulty

      @NotNull Difficulty getDifficulty()
      Gets the Difficulty of the world.
      Returns:
      The difficulty of the world.
    • getWorldFolder

      @NotNull File getWorldFolder()
      Gets the folder of this world on disk.
      Returns:
      The folder of this world.
    • getWorldType

      Deprecated.
      world type is only used to select the default word generation settings and is not stored in Vanilla worlds, making it impossible for this method to always return the correct value.
      Gets the type of this world.
      Returns:
      Type of this world.
    • canGenerateStructures

      boolean canGenerateStructures()
      Gets whether or not structures are being generated.
      Returns:
      True if structures are being generated.
    • isHardcore

      boolean isHardcore()
      Gets whether the world is hardcore or not. In a hardcore world the difficulty is locked to hard.
      Returns:
      hardcore status
    • setHardcore

      void setHardcore(boolean hardcore)
      Sets whether the world is hardcore or not. In a hardcore world the difficulty is locked to hard.
      Parameters:
      hardcore - Whether the world is hardcore
    • getTicksPerAnimalSpawns

      long getTicksPerAnimalSpawns()
      Gets the world's ticks per animal spawns value

      This value determines how many ticks there are between attempts to spawn animals.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn animals in this world every tick.
      • A value of 400 will mean the server will attempt to spawn animals in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, animal spawning will be disabled for this world. We recommend using setSpawnFlags(boolean, boolean) to control this instead.

      Minecraft default: 400.

      Returns:
      The world's ticks per animal spawns value
    • setTicksPerAnimalSpawns

      void setTicksPerAnimalSpawns(int ticksPerAnimalSpawns)
      Sets the world's ticks per animal spawns value

      This value determines how many ticks there are between attempts to spawn animals.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn animals in this world every tick.
      • A value of 400 will mean the server will attempt to spawn animals in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, animal spawning will be disabled for this world. We recommend using setSpawnFlags(boolean, boolean) to control this instead.

      Minecraft default: 400.

      Parameters:
      ticksPerAnimalSpawns - the ticks per animal spawns value you want to set the world to
    • getTicksPerMonsterSpawns

      long getTicksPerMonsterSpawns()
      Gets the world's ticks per monster spawns value

      This value determines how many ticks there are between attempts to spawn monsters.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn monsters in this world every tick.
      • A value of 400 will mean the server will attempt to spawn monsters in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, monsters spawning will be disabled for this world. We recommend using setSpawnFlags(boolean, boolean) to control this instead.

      Minecraft default: 1.

      Returns:
      The world's ticks per monster spawns value
    • setTicksPerMonsterSpawns

      void setTicksPerMonsterSpawns(int ticksPerMonsterSpawns)
      Sets the world's ticks per monster spawns value

      This value determines how many ticks there are between attempts to spawn monsters.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn monsters in this world on every tick.
      • A value of 400 will mean the server will attempt to spawn monsters in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, monsters spawning will be disabled for this world. We recommend using setSpawnFlags(boolean, boolean) to control this instead.

      Minecraft default: 1.

      Parameters:
      ticksPerMonsterSpawns - the ticks per monster spawns value you want to set the world to
    • getTicksPerWaterSpawns

      long getTicksPerWaterSpawns()
      Gets the world's ticks per water mob spawns value

      This value determines how many ticks there are between attempts to spawn water mobs.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn water mobs in this world every tick.
      • A value of 400 will mean the server will attempt to spawn water mobs in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, water mobs spawning will be disabled for this world.

      Minecraft default: 1.

      Returns:
      The world's ticks per water mob spawns value
    • setTicksPerWaterSpawns

      void setTicksPerWaterSpawns(int ticksPerWaterSpawns)
      Sets the world's ticks per water mob spawns value

      This value determines how many ticks there are between attempts to spawn water mobs.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn water mobs in this world on every tick.
      • A value of 400 will mean the server will attempt to spawn water mobs in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, water mobs spawning will be disabled for this world.

      Minecraft default: 1.

      Parameters:
      ticksPerWaterSpawns - the ticks per water mob spawns value you want to set the world to
    • getTicksPerWaterAmbientSpawns

      long getTicksPerWaterAmbientSpawns()
      Gets the default ticks per water ambient mob spawns value.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn water ambient mobs every tick.
      • A value of 400 will mean the server will attempt to spawn water ambient mobs every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, ambient mobs spawning will be disabled.

      Minecraft default: 1.

      Returns:
      the default ticks per water ambient mobs spawn value
    • setTicksPerWaterAmbientSpawns

      void setTicksPerWaterAmbientSpawns(int ticksPerAmbientSpawns)
      Sets the world's ticks per water ambient mob spawns value

      This value determines how many ticks there are between attempts to spawn water ambient mobs.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn water ambient mobs in this world on every tick.
      • A value of 400 will mean the server will attempt to spawn weater ambient mobs in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, water ambient mobs spawning will be disabled for this world.

      Minecraft default: 1.

      Parameters:
      ticksPerAmbientSpawns - the ticks per water ambient mob spawns value you want to set the world to
    • getTicksPerAmbientSpawns

      long getTicksPerAmbientSpawns()
      Gets the world's ticks per ambient mob spawns value

      This value determines how many ticks there are between attempts to spawn ambient mobs.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn ambient mobs in this world every tick.
      • A value of 400 will mean the server will attempt to spawn ambient mobs in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, ambient mobs spawning will be disabled for this world.

      Minecraft default: 1.

      Returns:
      The world's ticks per ambient mob spawns value
    • setTicksPerAmbientSpawns

      void setTicksPerAmbientSpawns(int ticksPerAmbientSpawns)
      Sets the world's ticks per ambient mob spawns value

      This value determines how many ticks there are between attempts to spawn ambient mobs.

      Example Usage:

      • A value of 1 will mean the server will attempt to spawn ambient mobs in this world on every tick.
      • A value of 400 will mean the server will attempt to spawn ambient mobs in this world every 400th tick.
      • A value below 0 will be reset back to Minecraft's default.

      Note: If set to 0, ambient mobs spawning will be disabled for this world.

      Minecraft default: 1.

      Parameters:
      ticksPerAmbientSpawns - the ticks per ambient mob spawns value you want to set the world to
    • getMonsterSpawnLimit

      int getMonsterSpawnLimit()
      Gets limit for number of monsters that can spawn in a chunk in this world
      Returns:
      The monster spawn limit
    • setMonsterSpawnLimit

      void setMonsterSpawnLimit(int limit)
      Sets the limit for number of monsters that can spawn in a chunk in this world

      Note: If set to a negative number the world will use the server-wide spawn limit instead.

      Parameters:
      limit - the new mob limit
    • getAnimalSpawnLimit

      int getAnimalSpawnLimit()
      Gets the limit for number of animals that can spawn in a chunk in this world
      Returns:
      The animal spawn limit
    • setAnimalSpawnLimit

      void setAnimalSpawnLimit(int limit)
      Sets the limit for number of animals that can spawn in a chunk in this world

      Note: If set to a negative number the world will use the server-wide spawn limit instead.

      Parameters:
      limit - the new mob limit
    • getWaterAnimalSpawnLimit

      int getWaterAnimalSpawnLimit()
      Gets the limit for number of water animals that can spawn in a chunk in this world
      Returns:
      The water animal spawn limit
    • setWaterAnimalSpawnLimit

      void setWaterAnimalSpawnLimit(int limit)
      Sets the limit for number of water animals that can spawn in a chunk in this world

      Note: If set to a negative number the world will use the server-wide spawn limit instead.

      Parameters:
      limit - the new mob limit
    • getWaterAmbientSpawnLimit

      int getWaterAmbientSpawnLimit()
      Gets user-specified limit for number of water ambient mobs that can spawn in a chunk.
      Returns:
      the water ambient spawn limit
    • setWaterAmbientSpawnLimit

      void setWaterAmbientSpawnLimit(int limit)
      Sets the limit for number of water ambient mobs that can spawn in a chunk in this world

      Note: If set to a negative number the world will use the server-wide spawn limit instead.

      Parameters:
      limit - the new mob limit
    • getAmbientSpawnLimit

      int getAmbientSpawnLimit()
      Gets the limit for number of ambient mobs that can spawn in a chunk in this world
      Returns:
      The ambient spawn limit
    • setAmbientSpawnLimit

      void setAmbientSpawnLimit(int limit)
      Sets the limit for number of ambient mobs that can spawn in a chunk in this world

      Note: If set to a negative number the world will use the server-wide spawn limit instead.

      Parameters:
      limit - the new mob limit
    • playSound

      void playSound(@NotNull Location location, @NotNull Sound sound, float volume, float pitch)
      Play a Sound at the provided Location in the World

      This function will fail silently if Location or Sound are null.

      Parameters:
      location - The location to play the sound
      sound - The sound to play
      volume - The volume of the sound
      pitch - The pitch of the sound
    • playSound

      void playSound(@NotNull Location location, @NotNull String sound, float volume, float pitch)
      Play a Sound at the provided Location in the World.

      This function will fail silently if Location or Sound are null. No sound will be heard by the players if their clients do not have the respective sound for the value passed.

      Parameters:
      location - the location to play the sound
      sound - the internal sound name to play
      volume - the volume of the sound
      pitch - the pitch of the sound
    • playSound

      void playSound(@NotNull Location location, @NotNull Sound sound, @NotNull SoundCategory category, float volume, float pitch)
      Play a Sound at the provided Location in the World.

      This function will fail silently if Location or Sound are null.

      Parameters:
      location - The location to play the sound
      sound - The sound to play
      category - the category of the sound
      volume - The volume of the sound
      pitch - The pitch of the sound
    • playSound

      void playSound(@NotNull Location location, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch)
      Play a Sound at the provided Location in the World.

      This function will fail silently if Location or Sound are null. No sound will be heard by the players if their clients do not have the respective sound for the value passed.

      Parameters:
      location - the location to play the sound
      sound - the internal sound name to play
      category - the category of the sound
      volume - the volume of the sound
      pitch - the pitch of the sound
    • getGameRules

      @NotNull String[] getGameRules()
      Get an array containing the names of all the GameRules.
      Returns:
      An array of GameRule names.
    • getGameRuleValue

      @Deprecated @Contract("null -> null; !null -> !null") @Nullable String getGameRuleValue(@Nullable String rule)
      Deprecated.
      Gets the current state of the specified rule

      Will return null if rule passed is null

      Parameters:
      rule - Rule to look up value of
      Returns:
      String value of rule
    • setGameRuleValue

      @Deprecated boolean setGameRuleValue(@NotNull String rule, @NotNull String value)
      Deprecated.
      Set the specified gamerule to specified value.

      The rule may attempt to validate the value passed, will return true if value was set.

      If rule is null, the function will return false.

      Parameters:
      rule - Rule to set
      value - Value to set rule to
      Returns:
      True if rule was set
    • isGameRule

      boolean isGameRule(@NotNull String rule)
      Checks if string is a valid game rule
      Parameters:
      rule - Rule to check
      Returns:
      True if rule exists
    • getGameRuleValue

      @Nullable <T> T getGameRuleValue(@NotNull GameRule<T> rule)
      Get the current value for a given GameRule.
      Type Parameters:
      T - the GameRule's type
      Parameters:
      rule - the GameRule to check
      Returns:
      the current value
    • getGameRuleDefault

      @Nullable <T> T getGameRuleDefault(@NotNull GameRule<T> rule)
      Get the default value for a given GameRule. This value is not guaranteed to match the current value.
      Type Parameters:
      T - the type of GameRule
      Parameters:
      rule - the rule to return a default value for
      Returns:
      the default value
    • setGameRule

      <T> boolean setGameRule(@NotNull GameRule<T> rule, @NotNull T newValue)
      Set the given GameRule's new value.
      Type Parameters:
      T - the value type of the GameRule
      Parameters:
      rule - the GameRule to update
      newValue - the new value
      Returns:
      true if the value was successfully set
    • getWorldBorder

      @NotNull WorldBorder getWorldBorder()
      Gets the world border for this world.
      Returns:
      The world border for this world.
    • spawnParticle

      void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count)
      Spawns the particle (the number of times specified by count) at the target location.
      Parameters:
      particle - the particle to spawn
      location - the location to spawn at
      count - the number of particles
    • spawnParticle

      void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count)
      Spawns the particle (the number of times specified by count) at the target location.
      Parameters:
      particle - the particle to spawn
      x - the position on the x axis to spawn at
      y - the position on the y axis to spawn at
      z - the position on the z axis to spawn at
      count - the number of particles
    • spawnParticle

      <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, @Nullable T data)
      Spawns the particle (the number of times specified by count) at the target location.
      Type Parameters:
      T - type of particle data (see Particle.getDataType()
      Parameters:
      particle - the particle to spawn
      location - the location to spawn at
      count - the number of particles
      data - the data to use for the particle or null, the type of this depends on Particle.getDataType()
    • spawnParticle

      <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, @Nullable T data)
      Spawns the particle (the number of times specified by count) at the target location.
      Type Parameters:
      T - type of particle data (see Particle.getDataType()
      Parameters:
      particle - the particle to spawn
      x - the position on the x axis to spawn at
      y - the position on the y axis to spawn at
      z - the position on the z axis to spawn at
      count - the number of particles
      data - the data to use for the particle or null, the type of this depends on Particle.getDataType()
    • spawnParticle

      void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Parameters:
      particle - the particle to spawn
      location - the location to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
    • spawnParticle

      void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Parameters:
      particle - the particle to spawn
      x - the position on the x axis to spawn at
      y - the position on the y axis to spawn at
      z - the position on the z axis to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
    • spawnParticle

      <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, @Nullable T data)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Type Parameters:
      T - type of particle data (see Particle.getDataType()
      Parameters:
      particle - the particle to spawn
      location - the location to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
      data - the data to use for the particle or null, the type of this depends on Particle.getDataType()
    • spawnParticle

      <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, @Nullable T data)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Type Parameters:
      T - type of particle data (see Particle.getDataType()
      Parameters:
      particle - the particle to spawn
      x - the position on the x axis to spawn at
      y - the position on the y axis to spawn at
      z - the position on the z axis to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
      data - the data to use for the particle or null, the type of this depends on Particle.getDataType()
    • spawnParticle

      void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, double extra)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Parameters:
      particle - the particle to spawn
      location - the location to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
      extra - the extra data for this particle, depends on the particle used (normally speed)
    • spawnParticle

      void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Parameters:
      particle - the particle to spawn
      x - the position on the x axis to spawn at
      y - the position on the y axis to spawn at
      z - the position on the z axis to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
      extra - the extra data for this particle, depends on the particle used (normally speed)
    • spawnParticle

      <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Type Parameters:
      T - type of particle data (see Particle.getDataType()
      Parameters:
      particle - the particle to spawn
      location - the location to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
      extra - the extra data for this particle, depends on the particle used (normally speed)
      data - the data to use for the particle or null, the type of this depends on Particle.getDataType()
    • spawnParticle

      <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Type Parameters:
      T - type of particle data (see Particle.getDataType()
      Parameters:
      particle - the particle to spawn
      x - the position on the x axis to spawn at
      y - the position on the y axis to spawn at
      z - the position on the z axis to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
      extra - the extra data for this particle, depends on the particle used (normally speed)
      data - the data to use for the particle or null, the type of this depends on Particle.getDataType()
    • spawnParticle

      <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data, boolean force)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Type Parameters:
      T - type of particle data (see Particle.getDataType()
      Parameters:
      particle - the particle to spawn
      location - the location to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
      extra - the extra data for this particle, depends on the particle used (normally speed)
      data - the data to use for the particle or null, the type of this depends on Particle.getDataType()
      force - whether to send the particle to players within an extended range and encourage their client to render it regardless of settings
    • spawnParticle

      <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data, boolean force)
      Spawns the particle (the number of times specified by count) at the target location. The position of each particle will be randomized positively and negatively by the offset parameters on each axis.
      Type Parameters:
      T - type of particle data (see Particle.getDataType()
      Parameters:
      particle - the particle to spawn
      x - the position on the x axis to spawn at
      y - the position on the y axis to spawn at
      z - the position on the z axis to spawn at
      count - the number of particles
      offsetX - the maximum random offset on the X axis
      offsetY - the maximum random offset on the Y axis
      offsetZ - the maximum random offset on the Z axis
      extra - the extra data for this particle, depends on the particle used (normally speed)
      data - the data to use for the particle or null, the type of this depends on Particle.getDataType()
      force - whether to send the particle to players within an extended range and encourage their client to render it regardless of settings
    • locateNearestStructure

      @Nullable Location locateNearestStructure(@NotNull Location origin, @NotNull StructureType structureType, int radius, boolean findUnexplored)
      Find the closest nearby structure of a given StructureType. Finding unexplored structures can, and will, block if the world is looking in chunks that gave not generated yet. This can lead to the world temporarily freezing while locating an unexplored structure.

      The radius is not a rigid square radius. Each structure may alter how many chunks to check for each iteration. Do not assume that only a radius x radius chunk area will be checked. For example, StructureType.WOODLAND_MANSION can potentially check up to 20,000 blocks away (or more) regardless of the radius used.

      This will not load or generate chunks. This can also lead to instances where the server can hang if you are only looking for unexplored structures. This is because it will keep looking further and further out in order to find the structure.

      Parameters:
      origin - where to start looking for a structure
      structureType - the type of structure to find
      radius - the radius, in chunks, around which to search
      findUnexplored - true to only find unexplored structures
      Returns:
      the closest Location, or null if no structure of the specified type exists.
    • getViewDistance

      int getViewDistance()
      Returns the view distance used for this world.
      Returns:
      the view distance used for this world
    • spigot

    • locateNearestRaid

      @Nullable Raid locateNearestRaid(@NotNull Location location, int radius)
      Finds the nearest raid close to the given location.
      Parameters:
      location - the origin location
      radius - the radius
      Returns:
      the closest Raid, or null if no raids were found
    • getRaids

      @NotNull List<Raid> getRaids()
      Gets all raids that are going on over this world.
      Returns:
      the list of all active raids
    • getEnderDragonBattle

      @Nullable DragonBattle getEnderDragonBattle()
      Get the DragonBattle associated with this world. If this world's environment is not World.Environment.THE_END, null will be returned.

      If an end world, a dragon battle instance will be returned regardless of whether or not a dragon is present in the world or a fight sequence has been activated. The dragon battle instance acts as a state holder.

      Returns:
      the dragon battle instance