From ec460b7767339e06197c27d6a01276ced4835f3e Mon Sep 17 00:00:00 2001 From: daoge_cmd <3523206925@qq.com> Date: Sun, 15 Sep 2024 16:49:32 +0800 Subject: [PATCH] docs: add javadocs for Chunk --- .../org/allaymc/api/world/chunk/Chunk.java | 135 +++++++++++++++++- 1 file changed, 133 insertions(+), 2 deletions(-) diff --git a/Allay-API/src/main/java/org/allaymc/api/world/chunk/Chunk.java b/Allay-API/src/main/java/org/allaymc/api/world/chunk/Chunk.java index 4a3a71d70..03897a79f 100644 --- a/Allay-API/src/main/java/org/allaymc/api/world/chunk/Chunk.java +++ b/Allay-API/src/main/java/org/allaymc/api/world/chunk/Chunk.java @@ -12,17 +12,36 @@ import java.util.stream.Collectors; /** - * Allay Project 2023/5/30 + * Chunk represents a 16x16 area in a world. + *

+ * All methods in this class are thread-safe. However, Frequent calls to methods in this class + * result in huge lock overhead. If you are sure that the instance won't be accessed by multiple threads, + * you can operate on unsafe chunk directly. To get the unsafe chunk, use {@link #toUnsafeChunk()}. * - * @author Cool_Loong + * @author Cool_Loong | daoge_cmd */ @ThreadSafe public interface Chunk extends UnsafeChunk { + /** + * Check if the chunk is loaded. + * + * @return {@code true} if the chunk is loaded, {@code false} otherwise + */ boolean isLoaded(); + /** + * Get the chunk loaders that load this chunk + * + * @return the chunk loaders + */ @UnmodifiableView Set getChunkLoaders(); + /** + * Get the player chunk loaders that load this chunk + * + * @return the player chunk loaders + */ @UnmodifiableView default Set getPlayerChunkLoaders() { return getChunkLoaders().stream() @@ -31,40 +50,152 @@ default Set getPlayerChunkLoaders() { .collect(Collectors.toSet()); } + /** + * Add a chunk loader to this chunk. + * + * @param chunkLoader the chunk loader to add + */ void addChunkLoader(ChunkLoader chunkLoader); + /** + * Remove a chunk loader from this chunk. + * + * @param chunkLoader the chunk loader to remove + */ void removeChunkLoader(ChunkLoader chunkLoader); + /** + * Get the number of chunk loaders that load this chunk. + * + * @return the number of chunk loaders + */ int getChunkLoaderCount(); + /** + * Add a chunk packet to the chunk. + *

+ * Chunk packet will be sent to all chunk loaders every tick. + * + * @param packet the packet to add + */ void addChunkPacket(BedrockPacket packet); + /** + * Add a chunk packet to the chunk. + *

+ * Chunk packet will be sent to chunk loaders that match the predicate every tick. + * + * @param packet the packet to add + * @param chunkLoaderPredicate the predicate to match chunk loaders + */ void addChunkPacket(BedrockPacket packet, Predicate chunkLoaderPredicate); + /** + * Send packet to all chunk loaders. + */ void sendChunkPacket(BedrockPacket packet); + /** + * Send packet to chunk loaders that match the predicate. + * + * @param packet the packet to send + * @param chunkLoaderPredicate the predicate to match chunk loaders + */ void sendChunkPacket(BedrockPacket packet, Predicate chunkLoaderPredicate); + /** + * Send all chunk packets which are added since last tick to all chunk loaders. + */ void sendChunkPackets(); + /** + * Compare and set block at the specified position. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + * @param expectedValue the expected block state. + * @param newValue the new block state. + * @param layer the layer to compare and set. + */ void compareAndSetBlock(int x, int y, int z, BlockState expectedValue, BlockState newValue, int layer); + /** + * Compare and set biome at the specified position. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + * @param expectedValue the expected biome type. + * @param newValue the new biome type. + */ void compareAndSetBiome(int x, int y, int z, BiomeType expectedValue, BiomeType newValue); + /** + * Compare and set block light at the specified position. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + * @param expectedValue the expected block light level. + * @param newValue the new block light level. + */ void compareAndSetBlockLight(int x, int y, int z, int expectedValue, int newValue); + /** + * Compare and set skylight at the specified position. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + * @param expectedValue the expected skylight level. + * @param newValue the new skylight level. + */ void compareAndSetSkyLight(int x, int y, int z, int expectedValue, int newValue); + /** + * Compare and set height at the specified position. + * + * @param x the x coordinate. + * @param z the z coordinate. + * @param expectedValue the expected height. + * @param newValue the new height. + */ void compareAndSetHeight(int x, int z, int expectedValue, int newValue); + /** + * Process the chunk with the specified operation. + *

+ * This method will only add a lock once, so it is more efficient than calling other methods + * in this class frequently. + * If you are going to get a range of blocks in the chunk, using this method will be an ideal choice + * to avoid lock overhead. + * + * @param operate the operation to process the chunk + */ void batchProcess(UnsafeChunkOperate operate); + /** + * Get the unsafe chunk of this chunk. + * + * @return the unsafe chunk + */ UnsafeChunk toUnsafeChunk(); + /** + * Spawn entities in this chunk to the specified player. + * + * @param player the player to spawn entities to + */ default void spawnEntitiesTo(EntityPlayer player) { getEntities().values().forEach(player::spawnEntity); } + /** + * Despawn entities in this chunk from the specified player. + * + * @param player the player to despawn entities from + */ default void despawnEntitiesFrom(EntityPlayer player) { getEntities().values().forEach(player::despawnEntity); }