Package net.minestom.server.instance

Class Instance

java.lang.Object
net.minestom.server.instance.Instance
All Implemented Interfaces:
Audience, ForwardingAudience, Pointered, PacketGroupingAudience, EventHandler<InstanceEvent>, Block.Getter, Block.Setter, Snapshotable, Taggable, TagReadable, TagWritable, Tickable, Schedulable
Direct Known Subclasses:
InstanceContainer, SharedInstance
public abstract class Instance extends Object implements Block.Getter, Block.Setter, Tickable, Schedulable, Snapshotable, EventHandler<InstanceEvent>, Taggable, PacketGroupingAudience
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 ThreadDispatcher of every partition/element changes.

  • Field Details

    • uuid

      protected UUID uuid

    • tagHandler

      protected TagHandler tagHandler

  • Constructor Details

    • Instance

      public Instance(@NotNull @NotNull UUID uuid, @NotNull @NotNull RegistryKey<DimensionType> dimensionType)
      Creates a new instance.
      Parameters:
      uuid - the UUID of the instance
      dimensionType - the DimensionType of the instance

    • Instance

      public Instance(@NotNull @NotNull UUID uuid, @NotNull @NotNull RegistryKey<DimensionType> dimensionType, @NotNull @NotNull net.kyori.adventure.key.Key dimensionName)
      Creates a new instance.
      Parameters:
      uuid - the UUID of the instance
      dimensionType - the DimensionType of the instance

    • Instance

      public Instance(@NotNull @NotNull DynamicRegistry<DimensionType> dimensionTypeRegistry, @NotNull @NotNull UUID uuid, @NotNull @NotNull RegistryKey<DimensionType> dimensionType, @NotNull @NotNull net.kyori.adventure.key.Key dimensionName)
      Creates a new instance.
      Parameters:
      uuid - the UUID of the instance
      dimensionType - the DimensionType of the instance

  • Method Details

    • scheduleNextTick

      public void scheduleNextTick(@NotNull @NotNull Consumer<Instance> callback)
      Schedules a task to be run during the next instance tick.
      Parameters:
      callback - the task to execute during the next instance tick

    • setBlock

      public void setBlock(int x, int y, int z, @NotNull @NotNull Block block)
      Specified by:
      setBlock in interface Block.Setter

    • setBlock

      public void setBlock(@NotNull @NotNull Point blockPosition, @NotNull @NotNull Block block, boolean doBlockUpdates)

    • setBlock

      public abstract void setBlock(int x, int y, int z, @NotNull @NotNull Block block, boolean doBlockUpdates)

    • placeBlock

      @Internal public boolean placeBlock(@NotNull BlockHandler.Placement placement)

    • placeBlock

      @Internal public abstract boolean placeBlock(@NotNull BlockHandler.Placement placement, boolean doBlockUpdates)

    • breakBlock

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

    • breakBlock

      @Internal public abstract boolean breakBlock(@NotNull @NotNull Player player, @NotNull @NotNull Point blockPosition, @NotNull @NotNull BlockFace blockFace, boolean doBlockUpdates)
      Does call PlayerBlockBreakEvent and send particle packets
      Parameters:
      player - the Player who break the block
      blockPosition - the position of the broken block
      doBlockUpdates - true to do block updates, false otherwise
      Returns:
      true if the block has been broken, false if it has been cancelled

    • loadChunk

      @NotNull public abstract @NotNull CompletableFuture<@NotNull Chunk> loadChunk(int chunkX, int chunkZ)
      Forces the generation of a Chunk, even if no file and Generator are defined.
      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z
      Returns:
      a CompletableFuture completed once the chunk has been loaded

    • loadChunk

      @NotNull public @NotNull CompletableFuture<@NotNull Chunk> loadChunk(@NotNull @NotNull Point point)
      Loads the chunk at the given Point with a callback.
      Parameters:
      point - the chunk position

    • loadOptionalChunk

      @NotNull public abstract @NotNull CompletableFuture<@Nullable Chunk> loadOptionalChunk(int chunkX, int chunkZ)
      Loads the chunk if the chunk is already loaded or if hasEnabledAutoChunkLoad() returns true.
      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z
      Returns:
      a CompletableFuture completed once the chunk has been processed, can be null if not loaded

    • loadOptionalChunk

      @NotNull public @NotNull CompletableFuture<@Nullable Chunk> loadOptionalChunk(@NotNull @NotNull Point point)
      Loads a Chunk (if hasEnabledAutoChunkLoad() returns true) at the given Point with a callback.
      Parameters:
      point - the chunk position
      Returns:
      a CompletableFuture completed once the chunk has been processed, null if not loaded

    • unloadChunk

      public abstract void unloadChunk(@NotNull @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.

      Parameters:
      chunk - the chunk to unload

    • unloadChunk

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

    • getChunk

      @Nullable public abstract @Nullable 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

    • isChunkLoaded

      public boolean isChunkLoaded(int chunkX, int chunkZ)
      Parameters:
      chunkX - the chunk X
      chunkZ - this chunk Z
      Returns:
      true if the chunk is loaded

    • isChunkLoaded

      public boolean isChunkLoaded(Point point)
      Parameters:
      point - coordinate of a block or other
      Returns:
      true if the chunk is loaded

    • saveInstance

      @NotNull public abstract @NotNull CompletableFuture<Void> saveInstance()
      Saves the current instance tags.

      Warning: only the global instance data will be saved, not chunks. You would need to call saveChunksToStorage() too.

      Returns:
      the future called once the instance data has been saved

    • saveChunkToStorage

      @NotNull public abstract @NotNull CompletableFuture<Void> saveChunkToStorage(@NotNull @NotNull Chunk chunk)
      Saves a Chunk to permanent storage.
      Parameters:
      chunk - the Chunk to save
      Returns:
      future called when the chunk is done saving

    • saveChunksToStorage

      @NotNull public abstract @NotNull CompletableFuture<Void> saveChunksToStorage()
      Saves multiple chunks to permanent storage.
      Returns:
      future called when the chunks are done saving

    • setChunkSupplier

      public abstract void setChunkSupplier(@NotNull @NotNull ChunkSupplier chunkSupplier)

    • getChunkSupplier

      public abstract ChunkSupplier getChunkSupplier()
      Gets the chunk supplier of the instance.
      Returns:
      the chunk supplier of the instance

    • generator

      @Nullable public abstract @Nullable Generator generator()
      Gets the generator associated with the instance
      Returns:
      the generator if any

    • setGenerator

      public abstract void setGenerator(@Nullable @Nullable Generator generator)
      Changes the generator of the instance
      Parameters:
      generator - the new generator, or null to disable generation

    • getChunks

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

    • 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 @NotNull Point point)
      Determines whether a position in the void.
      Parameters:
      point - the point in the world
      Returns:
      true if the point 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 RegistryKey<DimensionType> getDimensionType()
      Gets the instance DimensionType.
      Returns:
      the dimension of the instance

    • getCachedDimensionType

      @Internal @NotNull public @NotNull DimensionType getCachedDimensionType()

    • getDimensionName

      @NotNull public @NotNull String getDimensionName()
      Gets the instance dimension name.
      Returns:
      the dimension name of the instance

    • getWorldAge

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

    • setWorldAge

      public void setWorldAge(long worldAge)
      Sets the age of this instance in tick. It will send the age to all players. Will send new age to all players in the instance, unaffected by getTimeSynchronizationTicks()
      Parameters:
      worldAge - 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.

      If the time is negative, the vanilla client will not move the sun.

      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 getTimeSynchronizationTicks()

      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:
      IllegalStateException - if timeRate is lower than 0

    • getTimeSynchronizationTicks

      public int getTimeSynchronizationTicks()
      Gets the rate at which the client is updated with the current instance time
      Returns:
      the client update rate for time related packet

    • setTimeSynchronizationTicks

      public void setTimeSynchronizationTicks(int timeSynchronizationTicks)
      Changes the natural client time packet synchronization period, defaults to ServerFlag.SERVER_TICKS_PER_SECOND.

      Supplying 0 means that the client will never be synchronized with the current natural instance time (time will still change server-side)

      Parameters:
      timeSynchronizationTicks - the rate to update time in ticks

    • createTimePacket

      @Internal @NotNull public @NotNull TimeUpdatePacket createTimePacket()
      Creates a TimeUpdatePacket with the current age and time of this instance
      Returns:
      the TimeUpdatePacket with this instance data

    • getWorldBorder

      @NotNull public @NotNull WorldBorder getWorldBorder()
      Gets the current state of the instance WorldBorder.
      Returns:
      the WorldBorder for the instance of the current tick

    • setWorldBorder

      public void setWorldBorder(@NotNull @NotNull WorldBorder worldBorder, double transitionTime)
      Set the instance WorldBorder with a smooth transition.
      Parameters:
      worldBorder - the desired final state of the world border
      transitionTime - the time in seconds this world border's diameter will transition for (0 makes this instant)

    • setWorldBorder

      public void setWorldBorder(@NotNull @NotNull WorldBorder worldBorder)
      Set the instance WorldBorder with an instant transition. see setWorldBorder(WorldBorder, double).

    • createInitializeWorldBorderPacket

      @NotNull public @NotNull InitializeWorldBorderPacket createInitializeWorldBorderPacket()
      Creates the InitializeWorldBorderPacket sent to players who join this instance.

    • getEntities

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

    • getEntityById

      @Nullable public @Nullable Entity getEntityById(int id)
      Gets an entity based on its id (from Entity.getEntityId()).
      Parameters:
      id - the entity id
      Returns:
      the entity having the specified id, null if not found

    • getEntityByUuid

      @Nullable public @Nullable Entity getEntityByUuid(UUID uuid)
      Gets an entity based on its UUID (from Entity.getUuid()).
      Parameters:
      uuid - the entity UUID
      Returns:
      the entity having the specified uuid, null if not found

    • getPlayerByUuid

      @Nullable public @Nullable Player getPlayerByUuid(UUID uuid)
      Gets a player based on its UUID (from Entity.getUuid()).
      Parameters:
      uuid - the player UUID
      Returns:
      the player having the specified uuid, null if not found or not a player

    • getPlayers

      @NotNull public @NotNull Set<@NotNull Player> getPlayers()
      Gets the players in the instance;
      Specified by:
      getPlayers in interface PacketGroupingAudience
      Returns:
      an unmodifiable Set containing all the players in the instance

    • getCreatures

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

    • getExperienceOrbs

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

    • getChunkEntities

      @NotNull public @NotNull Set<@NotNull 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

    • getNearbyEntities

      @NotNull public @NotNull Collection<Entity> getNearbyEntities(@NotNull @NotNull Point point, double range)
      Gets nearby entities to the given position.
      Parameters:
      point - position to look at
      range - max range from the given point to collect entities at
      Returns:
      entities that are not further than the specified distance from the transmitted position.

    • getBlock

      @Nullable public @Nullable Block getBlock(int x, int y, int z, @NotNull @NotNull Block.Getter.Condition condition)
      Specified by:
      getBlock in interface Block.Getter

    • sendBlockAction

      public void sendBlockAction(@NotNull @NotNull Point 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:

    • getChunkAt

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

    • getChunkAt

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

    • getEntityTracker

      public EntityTracker getEntityTracker()

    • getUuid

      @NotNull public @NotNull UUID getUuid()
      Gets the instance unique id.
      Returns:
      the instance unique id

    • getUniqueId

      @Deprecated(forRemoval=true) @NotNull public @NotNull UUID getUniqueId()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Replace with getUuid()
      Gets the instance unique id.
      Returns:
      the instance unique id

    • 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.

      Specified by:
      tick in interface Tickable
      Parameters:
      time - the tick time in milliseconds

    • getWeather

      @NotNull public @NotNull Weather getWeather()
      Gets the weather of this instance
      Returns:
      the instance weather

    • setWeather

      public void setWeather(@NotNull @NotNull Weather weather, int transitionTicks)
      Sets the weather on this instance, transitions over time
      Parameters:
      weather - the new weather
      transitionTicks - the ticks to transition to new weather

    • setWeather

      public void setWeather(@NotNull @NotNull Weather weather)
      Sets the weather of this instance with a fixed transition
      Parameters:
      weather - the new weather

    • tagHandler

      @NotNull public @NotNull TagHandler tagHandler()
      Specified by:
      tagHandler in interface Taggable

    • scheduler

      @NotNull public @NotNull Scheduler scheduler()
      Specified by:
      scheduler in interface Schedulable

    • eventNode

      @Experimental @NotNull public @NotNull EventNode<InstanceEvent> eventNode()
      Specified by:
      eventNode in interface EventHandler<InstanceEvent>

    • updateSnapshot

      @NotNull public @NotNull InstanceSnapshot updateSnapshot(@NotNull @NotNull SnapshotUpdater updater)
      Description copied from interface: Snapshotable
      Updates the currently cached snapshot if required. The updater can be used to retrieve references to other snapshots while avoiding circular dependency. Be careful to do not store updater anywhere as its data will change when building requested references.

      This method is not thread-safe, and targeted at internal use since its execution rely on safe-points (e.g. end of ticks)

      Specified by:
      updateSnapshot in interface Snapshotable
      Parameters:
      updater - the snapshot updater/context
      Returns:
      the updated snapshot

    • playSoundExcept

      public void playSoundExcept(@Nullable @Nullable Player excludedPlayer, @NotNull @NotNull Sound sound, @NotNull @NotNull Point point)
      Plays a Sound at a given point, except to the excluded player
      Parameters:
      excludedPlayer - The player in the instance who won't receive the sound
      sound - The sound to play
      point - The point in this instance at which to play the sound

    • playSoundExcept

      public void playSoundExcept(@Nullable @Nullable Player excludedPlayer, @NotNull @NotNull Sound sound, double x, double y, double z)

    • playSoundExcept

      public void playSoundExcept(@Nullable @Nullable Player excludedPlayer, @NotNull @NotNull Sound sound, @NotNull Sound.Emitter emitter)

    • 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:
      IllegalStateException - If no ExplosionSupplier was supplied

    • explode

      public void explode(float centerX, float centerY, float centerZ, float strength, @Nullable @Nullable net.kyori.adventure.nbt.CompoundBinaryTag 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:
      IllegalStateException - If no ExplosionSupplier was supplied

    • getExplosionSupplier

      @Nullable public @Nullable 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 @Nullable ExplosionSupplier supplier)
      Registers the ExplosionSupplier to use in this instance.
      Parameters:
      supplier - the explosion supplier

    • pointers

      @NotNull public @NotNull Pointers pointers()
      Specified by:
      pointers in interface ForwardingAudience
      Specified by:
      pointers in interface Pointered

    • getBlockLight

      public int getBlockLight(int blockX, int blockY, int blockZ)

    • getSkyLight

      public int getSkyLight(int blockX, int blockY, int blockZ)