From a6e82d90ce54d3e9cfd26e81c1ef4c8ffc4bc32e Mon Sep 17 00:00:00 2001 From: Warrior <50800980+Warriorrrr@users.noreply.github.com> Date: Sun, 16 Feb 2025 19:13:35 +0100 Subject: [PATCH] [ci skip] Clarify getChunkAtAsyncUrgently javadocs (#12125) --- paper-api/src/main/java/org/bukkit/World.java | 76 ++++++++++++------- 1 file changed, 48 insertions(+), 28 deletions(-) diff --git a/paper-api/src/main/java/org/bukkit/World.java b/paper-api/src/main/java/org/bukkit/World.java index 27c4fcba6c..987a98074e 100644 --- a/paper-api/src/main/java/org/bukkit/World.java +++ b/paper-api/src/main/java/org/bukkit/World.java @@ -1481,14 +1481,14 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient /** * Requests a {@link Chunk} to be loaded at the given coordinates - * + *

* This method makes no guarantee on how fast the chunk will load, * and will return the chunk to the callback at a later time. - * + *

* You should use this method if you need a chunk but do not need it - * immediately, and you wish to let the server control the speed - * of chunk loads, keeping performance in mind. - * + * immediately, and you wish for it to be prioritised over other + * chunk loads in queue. + *

* The future will always be executed synchronously * on the main Server Thread. * @param loc Location to load the corresponding chunk from @@ -1500,14 +1500,14 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient /** * Requests a {@link Chunk} to be loaded at the given coordinates - * + *

* This method makes no guarantee on how fast the chunk will load, * and will return the chunk to the callback at a later time. - * + *

* You should use this method if you need a chunk but do not need it - * immediately, and you wish to let the server control the speed - * of chunk loads, keeping performance in mind. - * + * immediately, and you wish for it to be prioritised over other + * chunk loads in queue. + *

* The future will always be executed synchronously * on the main Server Thread. * @param loc Location to load the corresponding chunk from @@ -1520,14 +1520,14 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient /** * Requests a {@link Chunk} to be loaded at the given coordinates - * + *

* This method makes no guarantee on how fast the chunk will load, * and will return the chunk to the callback at a later time. - * + *

* You should use this method if you need a chunk but do not need it - * immediately, and you wish to let the server control the speed - * of chunk loads, keeping performance in mind. - * + * immediately, and you wish for it to be prioritised over other + * chunk loads in queue. + *

* The future will always be executed synchronously * on the main Server Thread. * @param block Block to load the corresponding chunk from @@ -1539,14 +1539,14 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient /** * Requests a {@link Chunk} to be loaded at the given coordinates - * + *

* This method makes no guarantee on how fast the chunk will load, * and will return the chunk to the callback at a later time. - * + *

* You should use this method if you need a chunk but do not need it - * immediately, and you wish to let the server control the speed - * of chunk loads, keeping performance in mind. - * + * immediately, and you wish for it to be prioritised over other + * chunk loads in queue. + *

* The future will always be executed synchronously * on the main Server Thread. * @param block Block to load the corresponding chunk from @@ -1559,25 +1559,45 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient /** * Requests a {@link Chunk} to be loaded at the given coordinates - * + *

* This method makes no guarantee on how fast the chunk will load, - * and will return the chunk to the callback at a later time. - * + * and will complete the future at a later time. + *

* You should use this method if you need a chunk but do not need it - * immediately, and you wish to let the server control the speed - * of chunk loads, keeping performance in mind. - * + * immediately, and you wish for it to be prioritised over other + * chunk loads in queue. + *

* The future will always be executed synchronously * on the main Server Thread. * - * @param x X Coord - * @param z Z Coord + * @param x Chunk x-coordinate + * @param z Chunk z-coordinate * @return Future that will resolve when the chunk is loaded */ default @NotNull java.util.concurrent.CompletableFuture getChunkAtAsyncUrgently(final int x, final int z) { return this.getChunkAtAsync(x, z, true, true); } + /** + * Requests a {@link Chunk} to be loaded at the given coordinates. + *

+ * This method makes no guarantee on how fast the chunk will load, + * and will return the chunk to the callback at a later time. + *

+ * You should use this method if you need a chunk but do not need it + * immediately, and you wish to let the server control the speed + * of chunk loads, keeping performance in mind. + *

+ * The future will always be executed synchronously + * on the main Server Thread. + * + * @param x Chunk x-coordinate + * @param z Chunk z-coordinate + * @param gen Should the chunk generate if it doesn't exist + * @param urgent If true, the chunk may be prioritised to be loaded above other chunks in queue + * + * @return Future that will resolve when the chunk is loaded + */ default @NotNull java.util.concurrent.CompletableFuture getChunkAtAsync(int x, int z, boolean gen, boolean urgent) { java.util.concurrent.CompletableFuture ret = new java.util.concurrent.CompletableFuture<>(); this.getChunkAtAsync(x, z, gen, urgent, ret::complete);