From 328c5ca0bc91b5014bf420e57365e818e0317e1c Mon Sep 17 00:00:00 2001 From: Antony Riley Date: Sat, 30 Mar 2013 02:18:52 +0200 Subject: [PATCH 1/3] Explicitely document methods as to whether they deal with chunk coordinates or block coordinates. --- src/main/java/org/bukkit/Chunk.java | 10 ++++++---- src/main/java/org/bukkit/World.java | 14 ++++++++------ 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/src/main/java/org/bukkit/Chunk.java b/src/main/java/org/bukkit/Chunk.java index 77651392..cf5460d0 100644 --- a/src/main/java/org/bukkit/Chunk.java +++ b/src/main/java/org/bukkit/Chunk.java @@ -10,16 +10,18 @@ public interface Chunk { /** - * Gets the X-coordinate of this chunk + * Gets the X-coordinate of this chunk. + * Note: This is the lowest block coordinate inside the chunk * - * @return X-coordinate + * @return X-coordinate in blocks */ int getX(); /** - * Gets the Z-coordinate of this chunk + * Gets the Z-coordinate of this chunk. + * Note: This is the lowest block coordinate inside the chunk * - * @return Z-coordinate + * @return Z-coordinate in blocks */ int getZ(); diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java index 266a59ad..e6606675 100644 --- a/src/main/java/org/bukkit/World.java +++ b/src/main/java/org/bukkit/World.java @@ -97,10 +97,11 @@ public interface World extends PluginMessageRecipient, Metadatable { public Block getHighestBlockAt(Location location); /** - * Gets the {@link Chunk} at the given coordinates + * Gets the {@link Chunk} at the given coordinates. + * Note: coordinates are in chunks, not blocks. * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @return Chunk at the given coordinates */ public Chunk getChunkAt(int x, int z); @@ -144,10 +145,11 @@ public interface World extends PluginMessageRecipient, Metadatable { public void loadChunk(Chunk chunk); /** - * Checks if the {@link Chunk} at the specified coordinates is loaded + * Checks if the {@link Chunk} at the specified coordinates is loaded. + * Note: coordinates are in chunks, not blocks. * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @return true if the chunk is loaded, otherwise false */ public boolean isChunkLoaded(int x, int z); From 235e45a3bd39eb9419f117a63251b34a1b11c89b Mon Sep 17 00:00:00 2001 From: Antony Riley Date: Wed, 3 Apr 2013 17:08:25 +0300 Subject: [PATCH 2/3] Various updates to World / Chunk javadocs. --- src/main/java/org/bukkit/Chunk.java | 2 + src/main/java/org/bukkit/World.java | 165 +++++++++++++++------------- 2 files changed, 89 insertions(+), 78 deletions(-) diff --git a/src/main/java/org/bukkit/Chunk.java b/src/main/java/org/bukkit/Chunk.java index cf5460d0..294d88d3 100644 --- a/src/main/java/org/bukkit/Chunk.java +++ b/src/main/java/org/bukkit/Chunk.java @@ -11,6 +11,7 @@ public interface Chunk { /** * Gets the X-coordinate of this chunk. + *

* Note: This is the lowest block coordinate inside the chunk * * @return X-coordinate in blocks @@ -19,6 +20,7 @@ public interface Chunk { /** * Gets the Z-coordinate of this chunk. + *

* Note: This is the lowest block coordinate inside the chunk * * @return Z-coordinate in blocks diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java index e6606675..1477bfcc 100644 --- a/src/main/java/org/bukkit/World.java +++ b/src/main/java/org/bukkit/World.java @@ -98,7 +98,6 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the {@link Chunk} at the given coordinates. - * Note: coordinates are in chunks, not blocks. * * @param x X-coordinate in chunks of the chunk * @param z Z-coordinate in chunks of the chunk @@ -146,7 +145,6 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Checks if the {@link Chunk} at the specified coordinates is loaded. - * Note: coordinates are in chunks, not blocks. * * @param x X-coordinate in chunks of the chunk * @param z Z-coordinate in chunks of the chunk @@ -157,37 +155,37 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Checks if the {@link Chunk} at the specified coordinates is loaded and in use by one or more players * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @return true if the chunk is loaded and in use by one or more players, otherwise false */ public boolean isChunkInUse(int x, int z); /** - * Loads the {@link Chunk} at the specified coordinates - *

+ * Loads the {@link Chunk} at the specified coordinates. + *

* If the chunk does not exist, it will be generated. * This method is analogous to {@link #loadChunk(int, int, boolean)} where generate is true. * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk */ public void loadChunk(int x, int z); /** * Loads the {@link Chunk} at the specified coordinates * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @param generate Whether or not to generate a chunk if it doesn't already exist * @return true if the chunk has loaded successfully, otherwise false */ public boolean loadChunk(int x, int z, boolean generate); /** - * Safely unloads and saves the {@link Chunk} at the specified coordinates - *

- * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true + * Safely unloads and saves the {@link Chunk} at the specified coordinates. + *

+ * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and save is true. * * @param chunk the chunk to unload * @return true if the chunk has unloaded successfully, otherwise false @@ -195,23 +193,23 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean unloadChunk(Chunk chunk); /** - * Safely unloads and saves the {@link Chunk} at the specified coordinates - *

- * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true + * Safely unloads and saves the {@link Chunk} at the specified coordinates. + *

+ * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and save is true. * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @return true if the chunk has unloaded successfully, otherwise false */ public boolean unloadChunk(int x, int z); /** - * Safely unloads and optionally saves the {@link Chunk} at the specified coordinates - *

- * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where save is true + * Safely unloads and optionally saves the {@link Chunk} at the specified coordinates. + *

+ * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where save is true. * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @param save Whether or not to save the chunk * @return true if the chunk has unloaded successfully, otherwise false */ @@ -220,8 +218,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Unloads and optionally saves the {@link Chunk} at the specified coordinates * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @param save Controls whether the chunk is saved * @param safe Controls whether to unload the chunk when players are nearby * @return true if the chunk has unloaded successfully, otherwise false @@ -229,12 +227,12 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean unloadChunk(int x, int z, boolean save, boolean safe); /** - * Safely queues the {@link Chunk} at the specified coordinates for unloading - *

- * This method is analogous to {@link #unloadChunkRequest(int, int, boolean)} where safe is true + * Safely queues the {@link Chunk} at the specified coordinates for unloading. + *

+ * This method is analogous to {@link #unloadChunkRequest(int, int, boolean)} where safe is true. * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @return true is the queue attempt was successful, otherwise false */ public boolean unloadChunkRequest(int x, int z); @@ -242,8 +240,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Queues the {@link Chunk} at the specified coordinates for unloading * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @param safe Controls whether to queue the chunk when players are nearby * @return Whether the chunk was actually queued */ @@ -252,8 +250,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Regenerates the {@link Chunk} at the specified coordinates * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @return Whether the chunk was actually regenerated */ public boolean regenerateChunk(int x, int z); @@ -261,8 +259,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Resends the {@link Chunk} to all clients * - * @param x X-coordinate of the chunk - * @param z Z-coordinate of the chunk + * @param x X-coordinate in chunks of the chunk + * @param z Z-coordinate in chunks of the chunk * @return Whether the chunk was actually refreshed */ public boolean refreshChunk(int x, int z); @@ -440,7 +438,7 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the relative in-game time of this world. - *

+ *

* The relative time is analogous to hours * 1000 * * @return The current relative time @@ -450,9 +448,9 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Sets the relative in-game time on the server. - *

+ *

* The relative time is analogous to hours * 1000 - *

+ *

* Note that setting the relative time below the current relative time will * actually move the clock forward a day. If you require to rewind time, please * see setFullTime @@ -471,8 +469,8 @@ public interface World extends PluginMessageRecipient, Metadatable { public long getFullTime(); /** - * Sets the in-game time on the server - *

+ * Sets the in-game time on the server. + *

* Note that this sets the full time of the world, which may cause adverse * effects such as breaking redstone clocks and any scheduled events * @@ -657,7 +655,7 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Spawn a {@link FallingBlock} entity at the given {@link Location} of the specified {@link Material}. * The material dictates what is falling. When the FallingBlock hits the ground, it will place that block. - *

+ *

* The Material must be a block type, check with {@link Material#isBlock() material.isBlock()}. * The Material may not be air. * @@ -763,7 +761,7 @@ public interface World extends PluginMessageRecipient, Metadatable { Biome getBiome(int x, int z); /** - * Sets the biome for the given block coordinates + * Sets the biome for the given block coordinates. * * @param x X coordinate of the block * @param z Z coordinate of the block @@ -773,7 +771,7 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the temperature for the given block coordinates. - *

+ *

* It is safe to run this method when the block does not exist, it will not create the block. * * @param x X coordinate of the block @@ -784,7 +782,7 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the humidity for the given block coordinates. - *

+ *

* It is safe to run this method when the block does not exist, it will not create the block. * * @param x X coordinate of the block @@ -795,7 +793,7 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the maximum height of this world. - *

+ *

* If the max height is 100, there are only blocks from y=0 to y=99. * * @return Maximum height of the world @@ -804,7 +802,7 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the sea level for this world. - *

+ *

* This is often half of {@link #getMaxHeight()} * * @return Sea level @@ -875,10 +873,10 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean canGenerateStructures(); /** - * Gets the world's ticks per animal spawns value - *

+ * Gets the world's ticks per animal spawns value. + *

* This value determines how many ticks there are between attempts to spawn animals. - *

+ *

* Example Usage: *