Class 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
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.
-
Nested Class Summary
Nested classes/interfaces inherited from interface net.minestom.server.instance.block.Block.Getter
Block.Getter.Condition
Nested classes/interfaces inherited from interface net.kyori.adventure.audience.ForwardingAudience
ForwardingAudience.Single
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionInstance
(@NotNull UUID uniqueId, @NotNull DimensionType dimensionType) Creates a new instance. -
Method Summary
Modifier and TypeMethodDescriptionabstract boolean
breakBlock
(@NotNull Player player, @NotNull Point blockPosition, @NotNull BlockFace blockFace) Does callPlayerBlockBreakEvent
and send particle packets@NotNull TimeUpdatePacket
Creates aTimeUpdatePacket
with the current age and time of this instanceabstract void
enableAutoChunkLoad
(boolean enable) When set to true, chunks will load automatically when requested.@NotNull EventNode<InstanceEvent>
void
explode
(float centerX, float centerY, float centerZ, float strength) Creates an explosion at the given position with the given strength.void
explode
(float centerX, float centerY, float centerZ, float strength, @Nullable org.jglrxavpok.hephaistos.nbt.NBTCompound additionalData) Creates an explosion at the given position with the given strength.abstract @Nullable Generator
Gets the generator associated with the instance@Nullable Block
getBlock
(int x, int y, int z, @NotNull Block.Getter.Condition condition) abstract @Nullable Chunk
getChunk
(int chunkX, int chunkZ) Gets the loadedChunk
at a position.@Nullable Chunk
getChunkAt
(double x, double z) Gets theChunk
at the given block position, null if not loaded.@Nullable Chunk
getChunkAt
(@NotNull Point point) getChunkEntities
(Chunk chunk) Gets the entities located in the chunk.abstract @NotNull Collection<@NotNull Chunk>
Gets all the instance's loaded chunks.@NotNull Set<@NotNull EntityCreature>
Deprecated.Gets the instanceDimensionType
.Gets the entities in the instance;@NotNull Set<@NotNull ExperienceOrb>
Deprecated.@Nullable ExplosionSupplier
Gets the registeredExplosionSupplier
, or null if none was provided.@NotNull PFInstanceSpace
Gets the instance space.@NotNull Collection<Entity>
getNearbyEntities
(@NotNull Point point, double range) Gets nearby entities to the given position.Gets the players in the instance;long
getTime()
Gets the current time in the instance (sun/moon).int
Gets the rate of the time passing, it is 1 by default@Nullable Duration
Gets the rate at which the client is updated with the current instance time@NotNull UUID
Gets the instance unique id.long
Gets the age of this instance in tick.@NotNull WorldBorder
Gets the instanceWorldBorder
;abstract boolean
Gets if the instance should auto load chunks.boolean
isChunkLoaded
(int chunkX, int chunkZ) boolean
isChunkLoaded
(Point point) abstract boolean
Determines whether a position in the void.boolean
Gets if the instance has been registered inInstanceManager
.abstract @NotNull CompletableFuture<@NotNull Chunk>
loadChunk
(int chunkX, int chunkZ) Forces the generation of aChunk
, even if no file andChunkGenerator
are defined.@NotNull CompletableFuture<@NotNull Chunk>
Loads the chunk at the givenPoint
with a callback.abstract @NotNull CompletableFuture<@Nullable Chunk>
loadOptionalChunk
(int chunkX, int chunkZ) Loads the chunk if the chunk is already loaded or ifhasEnabledAutoChunkLoad()
returns true.@NotNull CompletableFuture<@Nullable Chunk>
loadOptionalChunk
(@NotNull Point point) abstract boolean
placeBlock
(BlockHandler.Placement placement) @NotNull Pointers
pointers()
abstract @NotNull CompletableFuture<Void>
Saves multiple chunks to permanent storage.abstract @NotNull CompletableFuture<Void>
saveChunkToStorage
(@NotNull Chunk chunk) Saves aChunk
to permanent storage.abstract @NotNull CompletableFuture<Void>
Saves the current instance tags.void
scheduleNextTick
(@NotNull Consumer<Instance> callback) Schedules a task to be run during the next instance tick.@NotNull Scheduler
void
sendBlockAction
(@NotNull Point blockPosition, byte actionId, byte actionParam) Sends aBlockActionPacket
for all the viewers of the specific position.void
setChunkGenerator
(@Nullable ChunkGenerator chunkGenerator) Deprecated.void
setExplosionSupplier
(@Nullable ExplosionSupplier supplier) Registers theExplosionSupplier
to use in this instance.abstract void
setGenerator
(@Nullable Generator generator) Changes the generator of the instanceprotected void
setRegistered
(boolean registered) Changes the registered field.void
setTime
(long time) Changes the current time in the instance, from 0 to 24000.void
setTimeRate
(int timeRate) Changes the time rate of the instancevoid
setTimeUpdate
(@Nullable Duration timeUpdate) Changes the rate at which the client is updated about the time@NotNull TagHandler
void
tick
(long time) Performs a single tick in the instance, including scheduled tasks fromscheduleNextTick(Consumer)
.void
unloadChunk
(int chunkX, int chunkZ) Unloads the chunk at the given position.abstract void
unloadChunk
(@NotNull Chunk chunk) Schedules the removal of aChunk
, this method does not promise when it will be done.@NotNull InstanceSnapshot
updateSnapshot
(@NotNull SnapshotUpdater updater) Updates the currently cached snapshot if required.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface net.kyori.adventure.audience.Audience
deleteMessage, openBook, sendActionBar, sendMessage, sendMessage, sendMessage, sendMessage, sendMessage, sendMessage, sendMessage, sendMessage, sendMessage, sendMessage, sendPlayerListFooter, sendPlayerListHeader, sendPlayerListHeaderAndFooter, showTitle, stopSound
Methods inherited from interface net.minestom.server.instance.block.Block.Getter
getBlock, getBlock, getBlock
Methods inherited from interface net.minestom.server.instance.block.Block.Setter
setBlock, setBlock
Methods inherited from interface net.kyori.adventure.audience.ForwardingAudience
deleteMessage, filterAudience, forEachAudience, openBook, playSound, sendMessage, sendMessage, sendMessage, sendMessage, sendPlayerListFooter, sendPlayerListHeader
Methods inherited from interface net.minestom.server.adventure.audience.PacketGroupingAudience
audiences, clearTitle, hideBossBar, playSound, playSound, playSound, resetTitle, sendActionBar, sendGroupedPacket, sendMessage, sendPlayerListHeaderAndFooter, sendTitlePart, showBossBar, stopSound
Methods inherited from interface net.kyori.adventure.pointer.Pointered
get, getOrDefault, getOrDefaultFrom
-
Field Details
-
uniqueId
-
-
Constructor Details
-
Instance
Creates a new instance.- Parameters:
uniqueId
- theUUID
of the instancedimensionType
- theDimensionType
of the instance
-
-
Method Details
-
scheduleNextTick
Schedules a task to be run during the next instance tick.- Parameters:
callback
- the task to execute during the next instance tick
-
placeBlock
-
breakBlock
@Internal public abstract boolean breakBlock(@NotNull @NotNull Player player, @NotNull @NotNull Point blockPosition, @NotNull @NotNull BlockFace blockFace) Does callPlayerBlockBreakEvent
and send particle packets- Parameters:
player
- thePlayer
who break the blockblockPosition
- the position of the broken block- 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 aChunk
, even if no file andChunkGenerator
are defined.- Parameters:
chunkX
- the chunk XchunkZ
- the chunk Z- Returns:
- a
CompletableFuture
completed once the chunk has been loaded
-
loadChunk
Loads the chunk at the givenPoint
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 ifhasEnabledAutoChunkLoad()
returns true.- Parameters:
chunkX
- the chunk XchunkZ
- 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) - Parameters:
point
- the chunk position- Returns:
- a
CompletableFuture
completed once the chunk has been processed, null if not loaded
-
unloadChunk
Schedules the removal of aChunk
, 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 XchunkZ
- the chunk Z
-
getChunk
Gets the loadedChunk
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 XchunkZ
- 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 XchunkZ
- this chunk Z- Returns:
- true if the chunk is loaded
-
isChunkLoaded
- Parameters:
point
- coordinate of a block or other- Returns:
- true if the chunk is loaded
-
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 aChunk
to permanent storage.- Parameters:
chunk
- theChunk
to save- Returns:
- future called when the chunk is done saving
-
saveChunksToStorage
Saves multiple chunks to permanent storage.- Returns:
- future called when the chunks are done saving
-
setChunkGenerator
Deprecated.Changes the instanceChunkGenerator
.- Parameters:
chunkGenerator
- the newChunkGenerator
of the instance
-
generator
Gets the generator associated with the instance- Returns:
- the generator if any
-
setGenerator
Changes the generator of the instance- Parameters:
generator
- the new generator, or null to disable generation
-
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 usingloadChunk(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
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:
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 inInstanceManager
.- 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
Gets the instanceDimensionType
.- 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.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 instance1 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
- iftimeRate
is lower than 0
-
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
Changes the rate at which the client is updated about the timeSetting 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
Creates aTimeUpdatePacket
with the current age and time of this instance- Returns:
- the
TimeUpdatePacket
with this instance data
-
getWorldBorder
Gets the instanceWorldBorder
;- Returns:
- the
WorldBorder
linked to the instance
-
getEntities
Gets the entities in the instance;- Returns:
- an unmodifiable
Set
containing all the entities in the instance
-
getPlayers
Gets the players in the instance;- Specified by:
getPlayers
in interfacePacketGroupingAudience
- Returns:
- an unmodifiable
Set
containing all the players in the instance
-
getCreatures
Deprecated.Gets the creatures in the instance;- Returns:
- an unmodifiable
Set
containing all the creatures in the instance
-
getExperienceOrbs
Deprecated.Gets the experience orbs in the instance.- Returns:
- an unmodifiable
Set
containing all the experience orbs in the instance
-
getChunkEntities
Gets the entities located in the chunk. -
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 atrange
- 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 interfaceBlock.Getter
-
sendBlockAction
Sends aBlockActionPacket
for all the viewers of the specific position.- Parameters:
blockPosition
- the block positionactionId
- the action id, depends on the blockactionParam
- the action parameter, depends on the block- See Also:
-
- BlockActionPacket for the action id & param
-
getChunkAt
Gets theChunk
at the given block position, null if not loaded.- Parameters:
x
- the X positionz
- the Z position- Returns:
- the chunk at the given position, null if not loaded
-
getChunkAt
- Parameters:
point
- the position- Returns:
- the chunk at the given position, null if not loaded
-
getEntityTracker
-
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 fromscheduleNextTick(Consumer)
.Warning: this does not update chunks and entities.
-
tagHandler
- Specified by:
tagHandler
in interfaceTaggable
-
scheduler
- Specified by:
scheduler
in interfaceSchedulable
-
eventNode
- Specified by:
eventNode
in interfaceEventHandler<InstanceEvent>
-
updateSnapshot
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 storeupdater
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 interfaceSnapshotable
- 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 bygetExplosionSupplier()
.- Parameters:
centerX
- the center XcenterY
- the center YcenterZ
- the center Zstrength
- the strength of the explosion- Throws:
IllegalStateException
- If noExplosionSupplier
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 bygetExplosionSupplier()
.- Parameters:
centerX
- center X of the explosioncenterY
- center Y of the explosioncenterZ
- center Z of the explosionstrength
- the strength of the explosionadditionalData
- data to pass to the explosion supplier- Throws:
IllegalStateException
- If noExplosionSupplier
was supplied
-
getExplosionSupplier
Gets the registeredExplosionSupplier
, or null if none was provided.- Returns:
- the instance explosion supplier, null if none was provided
-
setExplosionSupplier
Registers theExplosionSupplier
to use in this instance.- Parameters:
supplier
- the explosion supplier
-
getInstanceSpace
Gets the instance space.Used by the pathfinder for entities.
- Returns:
- the instance space
-
pointers
- Specified by:
pointers
in interfaceForwardingAudience
- Specified by:
pointers
in interfacePointered
-
setGenerator(Generator)