From e3ad7ede8caaa57d7598f076478924d5a93b4230 Mon Sep 17 00:00:00 2001 From: boy0001 Date: Wed, 8 Oct 2014 22:51:19 +1100 Subject: [PATCH] some code documentation. --- .../plot/Configuration.java | 6 ++ .../plot/generator/DefaultPlotManager.java | 61 +++++++++++++++++-- .../plot/generator/DefaultPlotWorld.java | 21 +++++++ .../plot/generator/WorldGenerator.java | 4 ++ .../plot/generator/XPopulator.java | 8 +++ 5 files changed, 96 insertions(+), 4 deletions(-) diff --git a/PlotSquared/src/com/intellectualcrafters/plot/Configuration.java b/PlotSquared/src/com/intellectualcrafters/plot/Configuration.java index 20e54dd9e..24998e4ca 100644 --- a/PlotSquared/src/com/intellectualcrafters/plot/Configuration.java +++ b/PlotSquared/src/com/intellectualcrafters/plot/Configuration.java @@ -5,6 +5,7 @@ import java.util.List; import org.bukkit.block.Biome; + public class Configuration { public static final SettingValue STRING = new SettingValue("STRING") { @Override @@ -179,6 +180,11 @@ public class Configuration { } }; + /** + * + * Create your own SettingValue object to make the management of plotworld configuration easier + * + */ public static abstract class SettingValue { private String type; diff --git a/PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotManager.java b/PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotManager.java index 06114452c..f4a5e4f4b 100644 --- a/PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotManager.java +++ b/PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotManager.java @@ -25,14 +25,33 @@ import com.intellectualcrafters.plot.PlotWorld; public class DefaultPlotManager extends PlotManager { + /* + * Default implementation of getting a plot at a given location + * + * For a simplified explanation of the math involved: + * - Get the current coords + * - shift these numbers down to something relatable for a single plot + * (similar to reducing trigonometric functions down to the first quadrant) + * - e.g. If the plot size is 20 blocks, and we are at x=25, it's equivalent to x=5 for that specific plot + * + * From this, and knowing how thick the road is, we can say whether x=5 is road, or plot. + * The number of shifts done, is also counted, and this number gives us the PlotId + * + * + */ @Override public PlotId getPlotIdAbs(PlotWorld plotworld, Location loc) { DefaultPlotWorld dpw = ((DefaultPlotWorld) plotworld); + // get x,z loc int x = loc.getBlockX(); int z = loc.getBlockZ(); + // get plot size int size = dpw.PLOT_WIDTH + dpw.ROAD_WIDTH; + + // get size of path on bottom part, and top part of plot + // (As 0,0 is in the middle of a road, not the very start) int pathWidthLower; if ((dpw.ROAD_WIDTH % 2) == 0) { pathWidthLower = (int) (Math.floor(dpw.ROAD_WIDTH / 2) - 1); @@ -40,9 +59,9 @@ public class DefaultPlotManager extends PlotManager { pathWidthLower = (int) Math.floor(dpw.ROAD_WIDTH / 2); } + // calulating how many shifts need to be done int dx = x / size; int dz = z / size; - if (x < 0) { dx--; x += ((-dx) * size); @@ -52,19 +71,26 @@ public class DefaultPlotManager extends PlotManager { z += ((-dz) * size); } + // reducing to first plot int rx = (x) % size; int rz = (z) % size; + // checking if road (return null if so) int end = pathWidthLower + dpw.PLOT_WIDTH; boolean northSouth = (rz <= pathWidthLower) || (rz > end); boolean eastWest = (rx <= pathWidthLower) || (rx > end); - if (northSouth || eastWest) { return null; } + + // returning the plot id (based on the number of shifts required) return new PlotId(dx + 1, dz + 1); } + /* + * Check if a location is inside a specific plot(non-Javadoc) + * - For this implementation, we don't need to do anything fancier than referring to getPlotIdAbs(...) + */ @Override public boolean isInPlotAbs(PlotWorld plotworld, Location loc, Plot plot) { PlotId result = getPlotIdAbs(plotworld, loc); @@ -74,6 +100,10 @@ public class DefaultPlotManager extends PlotManager { return result==plot.id; } + /* + * Get the bottom plot loc + * (some basic math) + */ @Override public Location getPlotBottomLocAbs(PlotWorld plotworld, Plot plot) { DefaultPlotWorld dpw = ((DefaultPlotWorld) plotworld); @@ -86,7 +116,11 @@ public class DefaultPlotManager extends PlotManager { return new Location(Bukkit.getWorld(plot.world), x, 1, z); } - + + /* + * Get the top plot loc + * (some basic math) + */ @Override public Location getPlotTopLocAbs(PlotWorld plotworld, Plot plot) { DefaultPlotWorld dpw = ((DefaultPlotWorld) plotworld); @@ -100,6 +134,14 @@ public class DefaultPlotManager extends PlotManager { return new Location(Bukkit.getWorld(plot.world), x, 256, z); } + /* + * Clearing the plot needs to only consider removing the blocks + * - This implementation has used the SetCuboid function, as it is fast, and uses NMS code + * - It also makes use of the fact that deleting chunks is a lot faster than block updates + * + * This code is very messy, but you don't need to do something quite as complex unless you happen to have 512x512 sized plots + * + */ @Override public boolean clearPlot(Player player, Plot plot, boolean mega) { World world = player.getWorld(); @@ -225,6 +267,9 @@ public class DefaultPlotManager extends PlotManager { return true; } + /* + * Remove sign for a plot + */ @Override public boolean clearSign(Player player, Plot plot, boolean mega) { World world = player.getWorld(); @@ -235,6 +280,9 @@ public class DefaultPlotManager extends PlotManager { return true; } + /* + * Remove any entities, and teleport players inside a plot being cleared + */ @Override public boolean clearEntities(Player player, Plot plot, boolean mega) { World world = Bukkit.getWorld(plot.world); @@ -266,6 +314,9 @@ public class DefaultPlotManager extends PlotManager { return false; } + /* + * Set a plot biome + */ @Override public boolean setBiome(Player player, Plot plot, Biome biome) { @@ -289,7 +340,9 @@ public class DefaultPlotManager extends PlotManager { return true; } - // PLOT MERGING + /* + * PLOT MERGING + */ @Override public boolean createRoadEast(PlotWorld plotworld, Plot plot) { diff --git a/PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotWorld.java b/PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotWorld.java index a0005675d..72a202882 100644 --- a/PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotWorld.java +++ b/PlotSquared/src/com/intellectualcrafters/plot/generator/DefaultPlotWorld.java @@ -17,6 +17,12 @@ import com.intellectualcrafters.plot.PlotWorld; public class DefaultPlotWorld extends PlotWorld { + /* + * These variables are set to ensure fast access to config settings + * Strings are used as little as possible to optimize math performance in many of the functions/algorithms + * + */ + public boolean AUTO_MERGE; public static boolean AUTO_MERGE_DEFAULT = false; public boolean MOB_SPAWNING; @@ -182,10 +188,21 @@ public class DefaultPlotWorld extends PlotWorld { public double MERGE_PRICE; public static double MERGE_PRICE_DEFAULT = 100; + + /* + * Here we are just calling the super method, nothing special + */ public DefaultPlotWorld(String worldname) { super(worldname); } + /* + * CONFIG NODE | DEFAULT VALUE | DESCRIPTION | CONFIGURATION TYPE | REQUIRED FOR INITIAL SETUP + * + * Set the last boolean to false if you do not require a specific config node to be set while using the setup command + * - this may be useful if a config value can be changed at a later date, and has no impact on the actual world generation + * + */ @Override public ConfigurationNode[] getSettingNodes() { // TODO return a set of configuration nodes (used for setup command) @@ -217,6 +234,10 @@ public class DefaultPlotWorld extends PlotWorld { }; } + /* + * This method is called when a world loads. Make sure you set all your constants here. + * You are provided with the configuration section for that specific world. + */ @Override public void loadConfiguration(ConfigurationSection config) { this.MOB_SPAWNING = config.getBoolean("natural_mob_spawning"); diff --git a/PlotSquared/src/com/intellectualcrafters/plot/generator/WorldGenerator.java b/PlotSquared/src/com/intellectualcrafters/plot/generator/WorldGenerator.java index 032f0afe3..577fb6c87 100644 --- a/PlotSquared/src/com/intellectualcrafters/plot/generator/WorldGenerator.java +++ b/PlotSquared/src/com/intellectualcrafters/plot/generator/WorldGenerator.java @@ -20,6 +20,10 @@ import com.intellectualcrafters.plot.PlotWorld; * @auther Empire92 * @author Citymonstret * + * The default generator is very messy, as we have decided to try externalize all calculations from within the loop. + * - You will see a lot of slower implementations have a single for loop. + * - This is perfectly fine to do, it will just mean world generation may take somewhat longer + * */ public class WorldGenerator extends PlotGenerator { /* diff --git a/PlotSquared/src/com/intellectualcrafters/plot/generator/XPopulator.java b/PlotSquared/src/com/intellectualcrafters/plot/generator/XPopulator.java index f544479a7..73989f74f 100644 --- a/PlotSquared/src/com/intellectualcrafters/plot/generator/XPopulator.java +++ b/PlotSquared/src/com/intellectualcrafters/plot/generator/XPopulator.java @@ -16,6 +16,14 @@ import com.intellectualcrafters.plot.PlotWorld; * */ public class XPopulator extends BlockPopulator { + + /* + * Sorry, this isn't well documented at the moment. + * + * We advise you to take a look at a world generation tutorial for information about how a BlockPopulator works. + * + */ + private int X; private int Z; private long state;