Package net.minestom.server.instance

Class Instance

java.lang.Object
net.minestom.server.instance.Instance
All Implemented Interfaces:
DataContainer, EventHandler, BlockModifier
Direct Known Subclasses:
InstanceContainer, SharedInstance
public abstract class Instance
extends java.lang.Object
implements BlockModifier, EventHandler, DataContainer
Instances are what are called "worlds" in Minecraft, you can add an entity in it using Entity.setInstance(Instance).

An instance has entities and chunks, each instance contains its own entity list but the chunk implementation has to be defined, see InstanceContainer.

WARNING: when making your own implementation registering the instance manually is required with InstanceManager.registerInstance(Instance), and you need to be sure to signal the UpdateManager of the changes using UpdateManager.signalChunkLoad(Instance, int, int) and UpdateManager.signalChunkUnload(Instance, int, int).

  • Field Details

  • Constructor Details

    • Instance

      public Instance​(@NotNull java.util.UUID uniqueId, @NotNull DimensionType dimensionType)
      Creates a new instance.
      Parameters:
      uniqueId - the UUID of the instance
      dimensionType - the DimensionType of the instance

  • Method Details

    • scheduleNextTick

      public void scheduleNextTick​(@NotNull java.util.function.Consumer<Instance> callback)
      Schedules a task to be run during the next instance tick. It ensures that the task will be executed in the same thread as the instance and its chunks/entities (depending of the ThreadProvider).
      Parameters:
      callback - the task to execute during the next instance tick

    • refreshBlockStateId

      public abstract void refreshBlockStateId​(@NotNull BlockPosition blockPosition, short blockStateId)
      Used to change the id of the block in a specific BlockPosition.

      In case of a CustomBlock it does not remove it but only refresh its visual.

      Parameters:
      blockPosition - the block position
      blockStateId - the new block state

    • breakBlock

      public abstract boolean breakBlock​(@NotNull Player player, @NotNull BlockPosition blockPosition)
      Does call PlayerBlockBreakEvent and send particle packets
      Parameters:
      player - the Player who break the block
      blockPosition - the BlockPosition of the broken block
      Returns:
      true if the block has been broken, false if it has been cancelled

    • loadChunk

      public abstract void loadChunk​(int chunkX, int chunkZ, @Nullable ChunkCallback callback)
      Forces the generation of a Chunk, even if no file and ChunkGenerator are defined.
      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z
      callback - optional consumer called after the chunk has been generated, the returned chunk will never be null

    • loadOptionalChunk

      public abstract void loadOptionalChunk​(int chunkX, int chunkZ, @Nullable ChunkCallback callback)
      Loads the chunk if the chunk is already loaded or if hasEnabledAutoChunkLoad() returns true.
      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z
      callback - optional consumer called after the chunk has tried to be loaded, contains a chunk if it is successful, null otherwise

    • unloadChunk

      public abstract void unloadChunk​(@NotNull Chunk chunk)
      Schedules the removal of a Chunk, this method does not promise when it will be done.

      WARNING: during unloading, all entities other than Player will be removed.

      For InstanceContainer it is done during the next InstanceContainer.tick(long).

      Parameters:
      chunk - the chunk to unload

    • getChunk

      @Nullable public abstract Chunk getChunk​(int chunkX, int chunkZ)
      Gets the loaded Chunk at a position.

      WARNING: this should only return already-loaded chunk, use loadChunk(int, int) or similar to load one instead.

      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z
      Returns:
      the chunk at the specified position, null if not loaded

    • saveChunkToStorage

      public abstract void saveChunkToStorage​(@NotNull Chunk chunk, @Nullable java.lang.Runnable callback)
      Saves a Chunk to permanent storage.
      Parameters:
      chunk - the Chunk to save
      callback - optional callback called when the Chunk is done saving

    • saveChunksToStorage

      public abstract void saveChunksToStorage​(@Nullable java.lang.Runnable callback)
      Saves multiple chunks to permanent storage.
      Parameters:
      callback - optional callback called when the chunks are done saving

    • createBlockBatch

      public abstract BlockBatch createBlockBatch()
      Creates a new BlockBatch linked to this instance.
      Returns:
      a BlockBatch linked to the instance

    • createChunkBatch

      public abstract ChunkBatch createChunkBatch​(@NotNull Chunk chunk)
      Creates a new Chunk batch linked to this instance and the specified chunk.
      Parameters:
      chunk - the chunk to modify
      Returns:
      a ChunkBatch linked to chunk
      Throws:
      java.lang.NullPointerException - if chunk is null

    • getChunkGenerator

      @Nullable public abstract ChunkGenerator getChunkGenerator()
      Gets the instance ChunkGenerator.
      Returns:
      the ChunkGenerator of the instance

    • setChunkGenerator

      public abstract void setChunkGenerator​(@Nullable ChunkGenerator chunkGenerator)
      Changes the instance ChunkGenerator.
      Parameters:
      chunkGenerator - the new ChunkGenerator of the instance

    • getChunks

      @NotNull public abstract java.util.Collection<Chunk> getChunks()
      Gets all the instance's chunks.
      Returns:
      an unmodifiable containing all the loaded chunks of the instance

    • getStorageLocation

      @Nullable public abstract StorageLocation getStorageLocation()
      Gets the instance StorageLocation.
      Returns:
      the StorageLocation of the instance

    • setStorageLocation

      public abstract void setStorageLocation​(@Nullable StorageLocation storageLocation)
      Changes the instance StorageLocation.
      Parameters:
      storageLocation - the new StorageLocation of the instance

    • retrieveChunk

      protected abstract void retrieveChunk​(int chunkX, int chunkZ, @Nullable ChunkCallback callback)
      Used when a Chunk is not currently loaded in memory and need to be retrieved from somewhere else. Could be read from disk, or generated from scratch.

      Be sure to signal the chunk using UpdateManager.signalChunkLoad(Instance, int, int) and to cache that this chunk has been loaded.

      WARNING: it has to retrieve a chunk, this is not optional and should execute the callback in all case.

      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk X
      callback - the optional callback executed once the Chunk has been retrieved

    • createChunk

      protected abstract void createChunk​(int chunkX, int chunkZ, @Nullable ChunkCallback callback)
      Called to generated a new Chunk from scratch.

      Be sure to signal the chunk using UpdateManager.signalChunkLoad(Instance, int, int) and to cache that this chunk has been loaded.

      This is where you can put your chunk generation code.

      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z
      callback - the optional callback executed with the newly created Chunk

    • enableAutoChunkLoad

      public abstract void enableAutoChunkLoad​(boolean enable)
      When set to true, chunks will load automatically when requested. Otherwise using loadChunk(int, int) will be required to even spawn a player
      Parameters:
      enable - enable the auto chunk load

    • hasEnabledAutoChunkLoad

      public abstract boolean hasEnabledAutoChunkLoad()
      Gets if the instance should auto load chunks.
      Returns:
      true if auto chunk load is enabled, false otherwise

    • isInVoid

      public abstract boolean isInVoid​(@NotNull Position position)
      Determines whether a position in the void. If true, entities should take damage and die.

      Always returning false allow entities to survive in the void.

      Parameters:
      position - the position in the world
      Returns:
      true iif position is inside the void

    • isRegistered

      public boolean isRegistered()
      Gets if the instance has been registered in InstanceManager.
      Returns:
      true if the instance has been registered

    • setRegistered

      protected void setRegistered​(boolean registered)
      Changes the registered field.

      WARNING: should only be used by InstanceManager.

      Parameters:
      registered - true to mark the instance as registered

    • getDimensionType

      public DimensionType getDimensionType()
      Gets the instance DimensionType.
      Returns:
      the dimension of the instance

    • getWorldAge

      public long getWorldAge()
      Gets the age of this instance in tick.
      Returns:
      the age of this instance in tick

    • getTime

      public long getTime()
      Gets the current time in the instance (sun/moon).
      Returns:
      the time in the instance

    • setTime

      public void setTime​(long time)
      Changes the current time in the instance, from 0 to 24000.

      0 = sunrise 6000 = noon 12000 = sunset 18000 = midnight

      This method is unaffected by getTimeRate()

      It does send the new time to all players in the instance, unaffected by getTimeUpdate()

      Parameters:
      time - the new time of the instance

    • getTimeRate

      public int getTimeRate()
      Gets the rate of the time passing, it is 1 by default
      Returns:
      the time rate of the instance

    • setTimeRate

      public void setTimeRate​(int timeRate)
      Changes the time rate of the instance

      1 is the default value and can be set to 0 to be completely disabled (constant time)

      Parameters:
      timeRate - the new time rate of the instance
      Throws:
      java.lang.IllegalStateException - if timeRate is lower than 0

    • getTimeUpdate

      @Nullable public UpdateOption getTimeUpdate()
      Gets the rate at which the client is updated with the current instance time
      Returns:
      the client update rate for time related packet

    • setTimeUpdate

      public void setTimeUpdate​(@Nullable UpdateOption timeUpdate)
      Changes the rate at which the client is updated about the time

      Setting it to null means that the client will never know about time change (but will still change server-side)

      Parameters:
      timeUpdate - the new update rate concerning time

    • getWorldBorder

      @NotNull public WorldBorder getWorldBorder()
      Gets the instance WorldBorder;
      Returns:
      the WorldBorder linked to the instance

    • getEntities

      @NotNull public java.util.Set<Entity> getEntities()
      Gets the entities in the instance;
      Returns:
      an unmodifiable Set containing all the entities in the instance

    • getPlayers

      @NotNull public java.util.Set<Player> getPlayers()
      Gets the players in the instance;
      Returns:
      an unmodifiable Set containing all the players in the instance

    • getCreatures

      @NotNull public java.util.Set<EntityCreature> getCreatures()
      Gets the creatures in the instance;
      Returns:
      an unmodifiable Set containing all the creatures in the instance

    • getObjectEntities

      @NotNull public java.util.Set<ObjectEntity> getObjectEntities()
      Gets the object entities in the instance;
      Returns:
      an unmodifiable Set containing all the object entities in the instance

    • getExperienceOrbs

      @NotNull public java.util.Set<ExperienceOrb> getExperienceOrbs()
      Gets the experience orbs in the instance.
      Returns:
      an unmodifiable Set containing all the experience orbs in the instance

    • getChunkEntities

      @NotNull public java.util.Set<Entity> getChunkEntities​(Chunk chunk)
      Gets the entities located in the chunk.
      Parameters:
      chunk - the chunk to get the entities from
      Returns:
      an unmodifiable Set containing all the entities in a chunk, if chunk is unloaded, return an empty HashSet

    • refreshBlockStateId

      public void refreshBlockStateId​(int x, int y, int z, short blockStateId)
      Refreshes the visual block id at the position.

      WARNING: the custom block id at the position will not change.

      Parameters:
      x - the X position
      y - the Y position
      z - the Z position
      blockStateId - the new block state id

    • refreshBlockId

      public void refreshBlockId​(int x, int y, int z, @NotNull Block block)
      Refreshes the visual block id at the position.

      WARNING: the custom block id at the position will not change.

      Parameters:
      x - the X position
      y - the Y position
      z - the Z position
      block - the new visual block

    • refreshBlockId

      public void refreshBlockId​(@NotNull BlockPosition blockPosition, @NotNull Block block)
      Refreshes the visual block id at the BlockPosition.

      WARNING: the custom block id at the position will not change.

      Parameters:
      blockPosition - the block position
      block - the new visual block

    • loadChunk

      public void loadChunk​(int chunkX, int chunkZ)
      Loads the Chunk at the given position without any callback.

      WARNING: this is a non-blocking task.

      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z

    • loadChunk

      public void loadChunk​(@NotNull Position position, @Nullable ChunkCallback callback)
      Loads the chunk at the given Position with a callback.
      Parameters:
      position - the chunk position
      callback - the optional callback to run when the chunk is loaded

    • loadOptionalChunk

      public void loadOptionalChunk​(@NotNull Position position, @Nullable ChunkCallback callback)
      Loads a Chunk (if hasEnabledAutoChunkLoad() returns true) at the given Position with a callback.
      Parameters:
      position - the chunk position
      callback - the optional callback executed when the chunk is loaded (or with a null chunk if not)

    • unloadChunk

      public void unloadChunk​(int chunkX, int chunkZ)
      Unloads the chunk at the given position.
      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z

    • getBlockStateId

      public short getBlockStateId​(int x, int y, int z)
      Gives the block state id at the given position.
      Parameters:
      x - the X position
      y - the Y position
      z - the Z position
      Returns:
      the block state id at the position

    • getBlockStateId

      public short getBlockStateId​(float x, float y, float z)
      Gives the block state id at the given position.
      Parameters:
      x - the X position
      y - the Y position
      z - the Z position
      Returns:
      the block state id at the position

    • getBlockStateId

      public short getBlockStateId​(@NotNull BlockPosition blockPosition)
      Gives the block state id at the given BlockPosition.
      Parameters:
      blockPosition - the block position
      Returns:
      the block state id at the position

    • getCustomBlock

      @Nullable public CustomBlock getCustomBlock​(int x, int y, int z)
      Gets the custom block object at the given position.
      Parameters:
      x - the X position
      y - the Y position
      z - the Z position
      Returns:
      the custom block object at the position, null if not any

    • getCustomBlock

      @Nullable public CustomBlock getCustomBlock​(@NotNull BlockPosition blockPosition)
      Gets the custom block object at the given BlockPosition.
      Parameters:
      blockPosition - the block position
      Returns:
      the custom block object at the position, null if not any

    • sendBlockAction

      public void sendBlockAction​(@NotNull BlockPosition blockPosition, byte actionId, byte actionParam)
      Sends a BlockActionPacket for all the viewers of the specific position.
      Parameters:
      blockPosition - the block position
      actionId - the action id, depends on the block
      actionParam - the action parameter, depends on the block
      See Also:
      BlockActionPacket for the action id & param

    • getBlockData

      @Nullable public Data getBlockData​(int x, int y, int z)
      Gets the block data at the given position.
      Parameters:
      x - the X position
      y - the Y position
      z - the Z position
      Returns:
      the block data at the position, null if not any

    • getBlockData

      @Nullable public Data getBlockData​(@NotNull BlockPosition blockPosition)
      Gets the block Data at the given BlockPosition.
      Parameters:
      blockPosition - the block position
      Returns:
      the block data at the position, null if not any

    • setBlockData

      public void setBlockData​(int x, int y, int z, @Nullable Data data)
      Sets the block Data at the given BlockPosition.
      Parameters:
      x - the X position
      y - the Y position
      z - the Z position
      data - the data to be set, can be null

    • setBlockData

      public void setBlockData​(@NotNull BlockPosition blockPosition, @Nullable Data data)
      Sets the block Data at the given BlockPosition.
      Parameters:
      blockPosition - the block position
      data - the data to be set, can be null

    • getChunkAt

      @Nullable public Chunk getChunkAt​(float x, float z)
      Gets the Chunk at the given BlockPosition, null if not loaded.
      Parameters:
      x - the X position
      z - the Z position
      Returns:
      the chunk at the given position, null if not loaded

    • isChunkLoaded

      public boolean isChunkLoaded​(int chunkX, int chunkZ)
      Checks if the Chunk at the position is loaded.
      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z
      Returns:
      true if the chunk is loaded, false otherwise

    • getChunkAt

      @Nullable public Chunk getChunkAt​(@NotNull BlockPosition blockPosition)
      Gets the Chunk at the given BlockPosition, null if not loaded.
      Parameters:
      blockPosition - the chunk position
      Returns:
      the chunk at the given position, null if not loaded

    • getChunkAt

      @Nullable public Chunk getChunkAt​(@NotNull Position position)
      Gets the Chunk at the given Position, null if not loaded.
      Parameters:
      position - the chunk position
      Returns:
      the chunk at the given position, null if not loaded

    • saveChunkToStorage

      public void saveChunkToStorage​(@NotNull Chunk chunk)
      Saves a Chunk without any callback.
      Parameters:
      chunk - the chunk to save

    • saveChunksToStorage

      public void saveChunksToStorage()
      Saves all Chunk without any callback.

    • getUniqueId

      @NotNull public java.util.UUID getUniqueId()
      Gets the instance unique id.
      Returns:
      the instance unique id

    • getData

      public Data getData()
      Description copied from interface: DataContainer
      Gets the Data of this container.

      A DataContainer data is always optional, meaning that this will be null if no data has been defined.

      Specified by:
      getData in interface DataContainer
      Returns:
      the Data of this container, can be null

    • setData

      public void setData​(@Nullable Data data)
      Description copied from interface: DataContainer
      Sets the Data of this container.

      Default implementations are DataImpl and SerializableDataImpl depending on your use-case.

      Specified by:
      setData in interface DataContainer
      Parameters:
      data - the new Data of this container, null to remove it

    • getEventCallbacksMap

      @NotNull public java.util.Map<java.lang.Class<? extends Event>,​java.util.Collection<EventCallback>> getEventCallbacksMap()
      Description copied from interface: EventHandler
      Gets a Map containing all the listeners assigned to a specific Event type.
      Specified by:
      getEventCallbacksMap in interface EventHandler
      Returns:
      a Map with all the listeners

    • UNSAFE_addEntity

      public void UNSAFE_addEntity​(@NotNull Entity entity)
      Used when called Entity.setInstance(Instance), it is used to refresh viewable chunks and add viewers if entity is a Player.

      Warning: unsafe, you probably want to use Entity.setInstance(Instance) instead.

      Parameters:
      entity - the entity to add

    • UNSAFE_removeEntity

      public void UNSAFE_removeEntity​(@NotNull Entity entity)
      Used when an Entity is removed from the instance, it removes all of his viewers.

      Warning: unsafe, you probably want to set the entity to another instance.

      Parameters:
      entity - the entity to remove

    • addEntityToChunk

      public void addEntityToChunk​(@NotNull Entity entity, @NotNull Chunk chunk)
      Adds the specified Entity to the instance entities cache.

      Warning: this is done automatically when the entity move out of his chunk.

      Parameters:
      entity - the entity to add
      chunk - the chunk where the entity will be added

    • removeEntityFromChunk

      public void removeEntityFromChunk​(@NotNull Entity entity, @NotNull Chunk chunk)
      Removes the specified Entity to the instance entities cache.

      Warning: this is done automatically when the entity move out of his chunk.

      Parameters:
      entity - the entity to remove
      chunk - the chunk where the entity will be removed

    • scheduleUpdate

      public abstract void scheduleUpdate​(int time, @NotNull TimeUnit unit, @NotNull BlockPosition position)
      Schedules a block update at a given BlockPosition. Does nothing if no CustomBlock is present at position.

      Cancelled if the block changes between this call and the actual update.

      Parameters:
      time - in how long this update must be performed?
      unit - in what unit is the time expressed
      position - the location of the block to update

    • tick

      public void tick​(long time)
      Performs a single tick in the instance, including scheduled tasks from scheduleNextTick(Consumer).

      Warning: this does not update chunks and entities.

      Parameters:
      time - the tick time in milliseconds

    • explode

      public void explode​(float centerX, float centerY, float centerZ, float strength)
      Creates an explosion at the given position with the given strength. The algorithm used to compute damages is provided by getExplosionSupplier().
      Parameters:
      centerX - the center X
      centerY - the center Y
      centerZ - the center Z
      strength - the strength of the explosion
      Throws:
      java.lang.IllegalStateException - If no ExplosionSupplier was supplied

    • explode

      public void explode​(float centerX, float centerY, float centerZ, float strength, @Nullable Data additionalData)
      Creates an explosion at the given position with the given strength. The algorithm used to compute damages is provided by getExplosionSupplier().
      Parameters:
      centerX - center X of the explosion
      centerY - center Y of the explosion
      centerZ - center Z of the explosion
      strength - the strength of the explosion
      additionalData - data to pass to the explosion supplier
      Throws:
      java.lang.IllegalStateException - If no ExplosionSupplier was supplied

    • getExplosionSupplier

      @Nullable public ExplosionSupplier getExplosionSupplier()
      Gets the registered ExplosionSupplier, or null if none was provided.
      Returns:
      the instance explosion supplier, null if none was provided

    • setExplosionSupplier

      public void setExplosionSupplier​(@Nullable ExplosionSupplier supplier)
      Registers the ExplosionSupplier to use in this instance.
      Parameters:
      supplier - the explosion supplier

    • getInstanceSpace

      @NotNull public PFInstanceSpace getInstanceSpace()
      Gets the instance space.

      Used by the pathfinder for entities.

      Returns:
      the instance space