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

    • uniqueId

      protected UUID uniqueId

    • tagHandler

      protected TagHandler tagHandler

  • Constructor Details

    • Instance

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

    • Instance

      public Instance(@NotNull @NotNull UUID uniqueId, @NotNull @NotNull DimensionType dimensionType, @NotNull @NotNull NamespaceID dimensionName)
      Creates a new instance.
      Parameters:
      uniqueId - 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 ChunkGenerator 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

      @Experimental @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

    • setChunkGenerator

      @Deprecated public void setChunkGenerator(@Nullable @Nullable ChunkGenerator chunkGenerator)
      Deprecated.
      Use setGenerator(Generator)
      Changes the instance ChunkGenerator.
      Parameters:
      chunkGenerator - the new ChunkGenerator of the instance

    • 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 DimensionType getDimensionType()
      Gets the instance DimensionType.
      Returns:
      the dimension of the instance

    • 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

    • setWorldSpawnPosition

      public boolean setWorldSpawnPosition(@NotNull @NotNull Pos spawnPosition)
      Updates the spawn position of the instance. This method doesn't send the SpawnPositionPacket to the players.
      Parameters:
      spawnPosition - the new spawn position

    • setWorldSpawnPosition

      public boolean setWorldSpawnPosition(@NotNull @NotNull Pos spawnPosition, boolean sendPacket)
      Updates the spawn position of the instance. The underlying spawn position will only be updated if the new position is different from the current one. It sends the SpawnPositionPacket when the boolean option is true and the instance has players.
      Parameters:
      spawnPosition - the new spawn position
      sendPacket - if true, the new spawn position will be sent to all players in the instance

    • getWorldSpawnPosition

      @NotNull public @NotNull Pos getWorldSpawnPosition()
      Gets the spawn position of the instance. If the position is not set, it will return Pos.ZERO
      Returns:
      the spawn position of the instance

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

    • getTimeUpdate

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

    • 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 instance WorldBorder;
      Returns:
      the WorldBorder linked to the 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

    • 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

      @Experimental public EntityTracker getEntityTracker()

    • getUniqueId

      @NotNull public @NotNull UUID getUniqueId()
      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

    • 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 org.jglrxavpok.hephaistos.nbt.NBTCompound 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

    • getInstanceSpace

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

      Used by the pathfinder for entities.

      Returns:
      the instance space

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