Class Instance

java.lang.Object
net.minestom.server.instance.Instance
All Implemented Interfaces:
Audience, ForwardingAudience, Identified, 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, Pointered, Identified
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

    • INSTANCE_POINTERS_SUPPLIER

      protected static final PointersSupplier<Instance> INSTANCE_POINTERS_SUPPLIER

    • chunkViewDistance

      protected int chunkViewDistance

    • uuid

      protected UUID uuid

    • tagHandler

      protected TagHandler tagHandler

  • Constructor Details

  • Method Details

    • scheduleNextTick

      public void scheduleNextTick(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, Block block)
      Specified by:
      setBlock in interface Block.Setter

    • setBlock

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

    • setBlock

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

    • placeBlock

      @Internal public boolean placeBlock(BlockHandler.Placement placement)

    • placeBlock

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

    • breakBlock

      @Internal public boolean breakBlock(Player player, Point blockPosition, 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(Player player, Point blockPosition, 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

      public abstract CompletableFuture<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

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

    • loadOptionalChunk

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

      public CompletableFuture<@Nullable Chunk> loadOptionalChunk(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, can be null if not loaded

    • unloadChunk

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

    • invalidateSection

      public void invalidateSection(int sectionX, int sectionY, int sectionZ)

    • 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

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

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

    • saveChunksToStorage

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

    • setChunkSupplier

      public abstract void setChunkSupplier(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

    • generateChunk

      @Experimental public abstract CompletableFuture<Void> generateChunk(int chunkX, int chunkZ, Generator generator)
      Runs the provided Generator to generate a chunk at the given position.

      Loads the chunk if not already loaded.

      Parameters:
      chunkX - the chunk X
      chunkZ - the chunk Z
      generator - the generator to use
      Returns:
      a future called once the generation is complete

    • getChunks

      public abstract Collection<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(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 public DimensionType getCachedDimensionType()

    • getDimensionName

      public 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 public TimeUpdatePacket createTimePacket()
      Creates a TimeUpdatePacket with the current age and time of this instance
      Returns:
      the TimeUpdatePacket with this instance data

    • getWorldBorder

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

    • setWorldBorder

      public void setWorldBorder(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(WorldBorder worldBorder)
      Set the instance WorldBorder with an instant transition. see setWorldBorder(WorldBorder, double).

    • createInitializeWorldBorderPacket

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

    • getEntities

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

      public Set<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 public Set<EntityCreature> getCreatures()
      Deprecated.
      Gets the creatures in the instance;
      Returns:
      an unmodifiable Set containing all the creatures in the instance

    • getExperienceOrbs

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

    • getChunkEntities

      public 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

    • getNearbyEntities

      public Collection<Entity> getNearbyEntities(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, Block.Getter.Condition condition)
      Specified by:
      getBlock in interface Block.Getter

    • sendBlockAction

      public void sendBlockAction(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(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

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

    • getUniqueId

      @Deprecated(forRemoval=true) public 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, which may only be used as a delta and has no meaning in real life

    • getWeather

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

    • setWeather

      public void setWeather(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(Weather weather)
      Sets the weather of this instance with a fixed transition
      Parameters:
      weather - the new weather

    • viewDistance

      public int viewDistance()
      Gets the chunk view distance of this instance, which defaults to ServerFlag.CHUNK_VIEW_DISTANCE.
      Returns:
      The chunk view distance of this instance

    • viewDistance

      public void viewDistance(int newViewDistance)
      Sets the chunk view distance of this instance
      Parameters:
      newViewDistance - the new view distance

    • showBossBar

      public void showBossBar(BossBar bar)
      Shows a BossBar to all players in the instance and tracks it.
      Specified by:
      showBossBar in interface Audience
      Specified by:
      showBossBar in interface ForwardingAudience
      Specified by:
      showBossBar in interface PacketGroupingAudience
      Parameters:
      bar - a boss bar

    • hideBossBar

      public void hideBossBar(BossBar bar)
      Hides a BossBar from all players in the instance and stops tracking it.
      Specified by:
      hideBossBar in interface Audience
      Specified by:
      hideBossBar in interface ForwardingAudience
      Specified by:
      hideBossBar in interface PacketGroupingAudience
      Parameters:
      bar - a boss bar

    • bossBars

      @Experimental public @UnmodifiableView Set<BossBar> bossBars()

    • tagHandler

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

    • scheduler

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

    • eventNode

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

    • updateSnapshot

      public InstanceSnapshot updateSnapshot(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, Sound sound, 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, Sound sound, double x, double y, double z)

    • playSoundExcept

      public void playSoundExcept(@Nullable @Nullable Player excludedPlayer, Sound sound, 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 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

      @Contract(pure=true) public Pointers pointers()
      Specified by:
      pointers in interface ForwardingAudience
      Specified by:
      pointers in interface Pointered

    • identity

      @Contract(pure=true) public Identity identity()
      Specified by:
      identity in interface Identified

    • getBlockLight

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

    • getSkyLight

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