Package net.minestom.server.instance

Class InstanceContainer

java.lang.Object

net.minestom.server.instance.Instance

net.minestom.server.instance.InstanceContainer

All Implemented Interfaces:

DataContainer, EventHandler, BlockModifier

public class InstanceContainer
extends Instance

InstanceContainer is an instance that contains chunks in contrary to SharedInstance.

Field Summary

Fields

Modifier and Type	Field	Description
protected java.util.Set<Chunk>	scheduledChunksToRemove
protected InstanceContainer	srcInstance

Fields inherited from class net.minestom.server.instance.Instance

BLOCK_MANAGER, chunkEntities, creatures, entities, experienceOrbs, nextTick, objectEntities, players, uniqueId, UPDATE_MANAGER

Constructor Summary

Constructors

Constructor	Description
InstanceContainer(java.util.UUID uniqueId, DimensionType dimensionType, StorageLocation storageLocation)	Creates an InstanceContainer.

Method Summary

Modifier and Type	Method	Description
protected void	addSharedInstance(SharedInstance sharedInstance)	Assigns a SharedInstance to this container.
boolean	breakBlock(Player player, BlockPosition blockPosition)	Does call PlayerBlockBreakEvent and send particle packets
void	cacheChunk(Chunk chunk)	Adds a Chunk to the internal instance map.
InstanceContainer	copy()	Copies all the chunks of this instance and create a new instance container with all of them.
BlockBatch	createBlockBatch()	Creates a new BlockBatch linked to this instance.
protected void	createChunk(int chunkX, int chunkZ, ChunkCallback callback)	Called to generated a new Chunk from scratch.
ChunkBatch	createChunkBatch(Chunk chunk)	Creates a new Chunk batch linked to this instance and the specified chunk.
void	enableAutoChunkLoad(boolean enable)	When set to true, chunks will load automatically when requested.
Chunk	getChunk(int chunkX, int chunkZ)	Gets the loaded Chunk at a position.
ChunkGenerator	getChunkGenerator()	Gets the instance ChunkGenerator.
IChunkLoader	getChunkLoader()	Gets the IChunkLoader of this instance.
java.util.Collection<Chunk>	getChunks()	Gets all the instance chunks.
ChunkSupplier	getChunkSupplier()	Gets the current ChunkSupplier.
long	getLastBlockChangeTime()	Gets the last time at which a block changed.
java.util.List<SharedInstance>	getSharedInstances()	Gets all the SharedInstance linked to this container.
InstanceContainer	getSrcInstance()	Gets the instance from which this one has been copied.
StorageLocation	getStorageLocation()	Gets the instance StorageLocation.
boolean	hasEnabledAutoChunkLoad()	Gets if the instance should auto load chunks.
boolean	hasSharedInstances()	Gets if this instance has SharedInstance linked to it.
boolean	isInVoid(Position position)	Determines whether a position in the void.
void	loadChunk(int chunkX, int chunkZ, ChunkCallback callback)	Forces the generation of a Chunk, even if no file and ChunkGenerator are defined.
void	loadOptionalChunk(int chunkX, int chunkZ, ChunkCallback callback)	Loads the chunk if the chunk is already loaded or if Instance.hasEnabledAutoChunkLoad() returns true.
void	refreshBlockStateId(BlockPosition blockPosition, short blockStateId)	Used to change the id of the block in a specific BlockPosition.
void	refreshLastBlockChangeTime()	Signals the instance that a block changed.
protected void	retrieveChunk(int chunkX, int chunkZ, ChunkCallback callback)	Used when a Chunk is not currently loaded in memory and need to be retrieved from somewhere else.
void	saveChunksToStorage(java.lang.Runnable callback)	Saves multiple chunks to permanent storage.
void	saveChunkToStorage(Chunk chunk, java.lang.Runnable callback)	Saves a Chunk to permanent storage.
void	saveInstance()	Save the instance without callback.
void	saveInstance(java.lang.Runnable callback)	Saves the instance (Instance.getUniqueId() Instance.getData()) and call saveChunksToStorage(Runnable).
void	scheduleUpdate(int time, TimeUnit unit, BlockPosition position)	Schedules a block update at a given BlockPosition.
void	setBlockStateId(int x, int y, int z, short blockStateId, Data data)	Sets a block at a position.
void	setChunkGenerator(ChunkGenerator chunkGenerator)	Changes the instance ChunkGenerator.
void	setChunkLoader(IChunkLoader chunkLoader)	Changes the IChunkLoader of this instance (to change how chunks are retrieved when not already loaded).
void	setChunkSupplier(ChunkSupplier chunkSupplier)	Changes which type of Chunk implementation to use once one needs to be loaded.
void	setCustomBlock(int x, int y, int z, short customBlockId, Data data)	Sets a CustomBlock at a position.
void	setSeparateBlocks(int x, int y, int z, short blockStateId, short customBlockId, Data data)	Sets a CustomBlock at a position with a custom state id.
void	setStorageLocation(StorageLocation storageLocation)	Changes the instance StorageLocation.
void	tick(long time)	Performs a single tick in the instance, including scheduled tasks from Instance.scheduleNextTick(Consumer).
void	unloadChunk(Chunk chunk)	Schedules the removal of a Chunk, this method does not promise when it will be done.
protected void	UNSAFE_unloadChunks()	Unloads all waiting chunks.

Methods inherited from class net.minestom.server.instance.Instance

addEntityToChunk, explode, explode, getBlockData, getBlockData, getBlockStateId, getBlockStateId, getBlockStateId, getChunkAt, getChunkAt, getChunkAt, getChunkEntities, getCreatures, getCustomBlock, getCustomBlock, getData, getDimensionType, getEntities, getEventCallbacksMap, getExperienceOrbs, getExplosionSupplier, getInstanceSpace, getObjectEntities, getPlayers, getTime, getTimeRate, getTimeUpdate, getUniqueId, getWorldAge, getWorldBorder, isChunkLoaded, isRegistered, loadChunk, loadChunk, loadOptionalChunk, refreshBlockId, refreshBlockId, refreshBlockStateId, removeEntityFromChunk, saveChunksToStorage, saveChunkToStorage, scheduleNextTick, sendBlockAction, setBlockData, setBlockData, setData, setExplosionSupplier, setRegistered, setTime, setTimeRate, setTimeUpdate, unloadChunk, UNSAFE_addEntity, UNSAFE_removeEntity

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.minestom.server.instance.BlockModifier

setBlock, setBlock, setBlockStateId, setBlockStateId, setCustomBlock, setCustomBlock, setCustomBlock, setCustomBlock, setSeparateBlocks, setSeparateBlocks

Methods inherited from interface net.minestom.server.event.handler.EventHandler

addEventCallback, callCancellableEvent, callEvent, getEventCallbacks, getEventCallbacks, removeEventCallback

Field Details

scheduledChunksToRemove

protected final java.util.Set<Chunk> scheduledChunksToRemove

srcInstance

protected InstanceContainer srcInstance

Constructor Details

InstanceContainer

public InstanceContainer(@NotNull java.util.UUID uniqueId, @NotNull DimensionType dimensionType, @Nullable StorageLocation storageLocation)

Creates an InstanceContainer.

Parameters:

uniqueId - the unique id of the instance

dimensionType - the dimension type of the instance

storageLocation - the StorageLocation of the instance, can be null if you do not wish to save the instance later on

Method Details

setBlockStateId

public void setBlockStateId(int x, int y, int z, short blockStateId, @Nullable Data data)

Description copied from interface: BlockModifier

Sets a block at a position.

You can use BlockModifier.setBlock(int, int, int, Block) if you want it to be more explicit.

Parameters:

x - the block X

y - the block Y

z - the block Z

blockStateId - the block state id

data - the block Data, can be null

setCustomBlock

public void setCustomBlock(int x, int y, int z, short customBlockId, @Nullable Data data)

Description copied from interface: BlockModifier

Sets a CustomBlock at a position.

The custom block id should be the one returned by CustomBlock.getCustomBlockId().

Parameters:

x - the block X

y - the block Y

z - the block Z

customBlockId - the custom block id

data - the block Data, can be null

setSeparateBlocks

public void setSeparateBlocks(int x, int y, int z, short blockStateId, short customBlockId, @Nullable Data data)

Description copied from interface: BlockModifier

Sets a CustomBlock at a position with a custom state id.

The custom block id should be the one returned by CustomBlock.getCustomBlockId(), and the block state id can be anything you want, state id can be retrieved using Block.getBlockId().

Parameters:

x - the block X

y - the block Y

z - the block Z

blockStateId - the block state id

customBlockId - the custom block id

data - the block Data, can be null

refreshBlockStateId

public void refreshBlockStateId(@NotNull BlockPosition blockPosition, short blockStateId)

Description copied from class: Instance

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.

Specified by:

refreshBlockStateId in class Instance

Parameters:

blockPosition - the block position

blockStateId - the new block state

breakBlock

public boolean breakBlock(@NotNull Player player, @NotNull BlockPosition blockPosition)

Description copied from class: Instance

Does call PlayerBlockBreakEvent and send particle packets

Specified by:

breakBlock in class Instance

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 void loadChunk(int chunkX, int chunkZ, @Nullable ChunkCallback callback)

Description copied from class: Instance

Forces the generation of a Chunk, even if no file and ChunkGenerator are defined.

Specified by:

loadChunk in class Instance

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 void loadOptionalChunk(int chunkX, int chunkZ, @Nullable ChunkCallback callback)

Description copied from class: Instance

Loads the chunk if the chunk is already loaded or if Instance.hasEnabledAutoChunkLoad() returns true.

Specified by:

loadOptionalChunk in class Instance

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 void unloadChunk(@NotNull Chunk chunk)

Description copied from class: Instance

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 tick(long).

Specified by:

unloadChunk in class Instance

Parameters:

chunk - the chunk to unload

getChunk

public Chunk getChunk(int chunkX, int chunkZ)

Description copied from class: Instance

Gets the loaded Chunk at a position.

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

Specified by:

getChunk in class Instance

Parameters:

chunkX - the chunk X

chunkZ - the chunk Z

Returns:

the chunk at the specified position, null if not loaded

saveInstance

public void saveInstance(@Nullable java.lang.Runnable callback)

Saves the instance (Instance.getUniqueId() Instance.getData()) and call saveChunksToStorage(Runnable).

WARNING: Instance.getData() needs to be a SerializableData in order to be saved.

Parameters:

callback - the optional callback once the saving is done

saveInstance

public void saveInstance()

Save the instance without callback.

See Also:

saveInstance(Runnable)

saveChunkToStorage

public void saveChunkToStorage(@NotNull Chunk chunk, java.lang.Runnable callback)

Description copied from class: Instance

Saves a Chunk to permanent storage.

Specified by:

saveChunkToStorage in class Instance

Parameters:

chunk - the Chunk to save

callback - optional callback called when the Chunk is done saving

saveChunksToStorage

public void saveChunksToStorage(@Nullable java.lang.Runnable callback)

Description copied from class: Instance

Saves multiple chunks to permanent storage.

Specified by:

saveChunksToStorage in class Instance

Parameters:

callback - optional callback called when the chunks are done saving

createBlockBatch

public BlockBatch createBlockBatch()

Description copied from class: Instance

Creates a new BlockBatch linked to this instance.

Specified by:

createBlockBatch in class Instance

Returns:

a BlockBatch linked to the instance

createChunkBatch

public ChunkBatch createChunkBatch(@NotNull Chunk chunk)

Description copied from class: Instance

Creates a new Chunk batch linked to this instance and the specified chunk.

Specified by:

createChunkBatch in class Instance

Parameters:

chunk - the chunk to modify

Returns:

a ChunkBatch linked to chunk

retrieveChunk

protected void retrieveChunk(int chunkX, int chunkZ, @Nullable ChunkCallback callback)

Description copied from class: Instance

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.

Specified by:

retrieveChunk in class Instance

Parameters:

chunkX - the chunk X

chunkZ - the chunk X

callback - the optional callback executed once the Chunk has been retrieved

createChunk

protected void createChunk(int chunkX, int chunkZ, @Nullable ChunkCallback callback)

Description copied from class: Instance

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.

Specified by:

createChunk in class Instance

Parameters:

chunkX - the chunk X

chunkZ - the chunk Z

callback - the optional callback executed with the newly created Chunk

enableAutoChunkLoad

public void enableAutoChunkLoad(boolean enable)

Description copied from class: Instance

When set to true, chunks will load automatically when requested. Otherwise using Instance.loadChunk(int, int) will be required to even spawn a player

Specified by:

enableAutoChunkLoad in class Instance

Parameters:

enable - enable the auto chunk load

hasEnabledAutoChunkLoad

public boolean hasEnabledAutoChunkLoad()

Description copied from class: Instance

Gets if the instance should auto load chunks.

Specified by:

hasEnabledAutoChunkLoad in class Instance

Returns:

true if auto chunk load is enabled, false otherwise

isInVoid

public boolean isInVoid(@NotNull Position position)

Description copied from class: Instance

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.

Specified by:

isInVoid in class Instance

Parameters:

position - the position in the world

Returns:

true iif position is inside the void

setChunkSupplier

public void setChunkSupplier(@NotNull ChunkSupplier chunkSupplier)

Changes which type of Chunk implementation to use once one needs to be loaded.

Uses DynamicChunk by default.

WARNING: if you need to save this instance's chunks later, the code needs to be predictable for IChunkLoader.loadChunk(Instance, int, int, ChunkCallback) to create the correct type of Chunk. tl;dr: Need chunk save = no random type.

Parameters:

chunkSupplier - the new ChunkSupplier of this instance, chunks need to be non-null

Throws:

java.lang.NullPointerException - if chunkSupplier is null

getChunkSupplier

public ChunkSupplier getChunkSupplier()

Gets the current ChunkSupplier.

You shouldn't use it to generate a new chunk, but as a way to view which one is currently in use.

Returns:

the current ChunkSupplier

getSharedInstances

public java.util.List<SharedInstance> getSharedInstances()

Gets all the SharedInstance linked to this container.

Returns:

an unmodifiable List containing all the SharedInstance linked to this container

hasSharedInstances

public boolean hasSharedInstances()

Gets if this instance has SharedInstance linked to it.

Returns:

true if getSharedInstances() is not empty

addSharedInstance

protected void addSharedInstance(SharedInstance sharedInstance)

Assigns a SharedInstance to this container.

Only used by InstanceManager, mostly unsafe.

Parameters:

sharedInstance - the shared instance to assign to this container

copy

public InstanceContainer copy()

Copies all the chunks of this instance and create a new instance container with all of them.

Chunks are copied with Chunk.copy(int, int), UUID is randomized, DimensionType is passed over and the StorageLocation is null.

Returns:

an InstanceContainer with the exact same chunks as 'this'

See Also:

to retrieve the "creation source" of the copied instance

getSrcInstance

@Nullable public InstanceContainer getSrcInstance()

Gets the instance from which this one has been copied.

Only present if this instance has been created with copy().

Returns:

the instance source, null if not created by a copy

See Also:

to create a copy of this instance with 'this' as the source

getLastBlockChangeTime

public long getLastBlockChangeTime()

Gets the last time at which a block changed.

Returns:

the time at which the last block changed in milliseconds, 0 if never

refreshLastBlockChangeTime

public void refreshLastBlockChangeTime()

Signals the instance that a block changed.

Useful if you change blocks values directly using a Chunk object.

cacheChunk

public void cacheChunk(@NotNull Chunk chunk)

Adds a Chunk to the internal instance map.

WARNING: the chunk will not automatically be sent to players and UpdateManager.signalChunkLoad(Instance, int, int) must be called manually.

Parameters:

chunk - the chunk to cache

getChunkGenerator

public ChunkGenerator getChunkGenerator()

Description copied from class: Instance

Gets the instance ChunkGenerator.

Specified by:

getChunkGenerator in class Instance

Returns:

the ChunkGenerator of the instance

setChunkGenerator

public void setChunkGenerator(ChunkGenerator chunkGenerator)

Description copied from class: Instance

Changes the instance ChunkGenerator.

Specified by:

setChunkGenerator in class Instance

Parameters:

chunkGenerator - the new ChunkGenerator of the instance

getChunks

@NotNull public java.util.Collection<Chunk> getChunks()

Gets all the instance chunks.

Specified by:

getChunks in class Instance

Returns:

the chunks of this instance

getStorageLocation

public StorageLocation getStorageLocation()

Description copied from class: Instance

Gets the instance StorageLocation.

Specified by:

getStorageLocation in class Instance

Returns:

the StorageLocation of the instance

setStorageLocation

public void setStorageLocation(StorageLocation storageLocation)

Description copied from class: Instance

Changes the instance StorageLocation.

Specified by:

setStorageLocation in class Instance

Parameters:

storageLocation - the new StorageLocation of the instance

getChunkLoader

public IChunkLoader getChunkLoader()

Gets the IChunkLoader of this instance.

Returns:

the IChunkLoader of this instance

setChunkLoader

public void setChunkLoader(IChunkLoader chunkLoader)

Changes the IChunkLoader of this instance (to change how chunks are retrieved when not already loaded).

Parameters:

chunkLoader - the new IChunkLoader

scheduleUpdate

public void scheduleUpdate(int time, @NotNull TimeUnit unit, @NotNull BlockPosition position)

Description copied from class: Instance

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.

Specified by:

scheduleUpdate in class Instance

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)

Description copied from class: Instance

Performs a single tick in the instance, including scheduled tasks from Instance.scheduleNextTick(Consumer).

Warning: this does not update chunks and entities.

Overrides:

tick in class Instance

Parameters:

time - the tick time in milliseconds

UNSAFE_unloadChunks

protected void UNSAFE_unloadChunks()

Unloads all waiting chunks.

Unsafe because it has to be done on the same thread as the instance/chunks tick update.