From 70bca47be7d41812f34d1a09ac5b293417eb4957 Mon Sep 17 00:00:00 2001 From: sk89q Date: Sat, 26 Jul 2014 00:28:19 -0700 Subject: [PATCH] Clean up Javadocs for the blocks.* package. --- .../sk89q/worldedit/masks/FuzzyBlockMask.java | 3 +- .../com/sk89q/worldedit/blocks/BaseBlock.java | 89 ++++--- .../com/sk89q/worldedit/blocks/BaseItem.java | 6 +- .../sk89q/worldedit/blocks/BaseItemStack.java | 6 +- .../com/sk89q/worldedit/blocks/BlockData.java | 56 ++--- .../com/sk89q/worldedit/blocks/BlockType.java | 225 +++++++++++------- .../com/sk89q/worldedit/blocks/Blocks.java | 49 ++++ .../sk89q/worldedit/blocks/ClothColor.java | 34 ++- .../com/sk89q/worldedit/blocks/ItemID.java | 4 +- .../com/sk89q/worldedit/blocks/ItemType.java | 64 ++--- .../worldedit/blocks/TileEntityBlock.java | 5 +- .../function/mask/FuzzyBlockMask.java | 5 +- 12 files changed, 337 insertions(+), 209 deletions(-) create mode 100644 src/main/java/com/sk89q/worldedit/blocks/Blocks.java diff --git a/src/legacy/java/com/sk89q/worldedit/masks/FuzzyBlockMask.java b/src/legacy/java/com/sk89q/worldedit/masks/FuzzyBlockMask.java index 586422e0c..8118d6308 100644 --- a/src/legacy/java/com/sk89q/worldedit/masks/FuzzyBlockMask.java +++ b/src/legacy/java/com/sk89q/worldedit/masks/FuzzyBlockMask.java @@ -22,6 +22,7 @@ package com.sk89q.worldedit.masks; import com.sk89q.worldedit.EditSession; import com.sk89q.worldedit.Vector; import com.sk89q.worldedit.blocks.BaseBlock; +import com.sk89q.worldedit.blocks.Blocks; import java.util.HashSet; import java.util.Set; @@ -59,6 +60,6 @@ public class FuzzyBlockMask extends AbstractMask { @Override public boolean matches(EditSession editSession, Vector pos) { BaseBlock compare = new BaseBlock(editSession.getBlockType(pos), editSession.getBlockData(pos)); - return BaseBlock.containsFuzzy(filter, compare); + return Blocks.containsFuzzy(filter, compare); } } diff --git a/src/main/java/com/sk89q/worldedit/blocks/BaseBlock.java b/src/main/java/com/sk89q/worldedit/blocks/BaseBlock.java index d89ff8e03..e909296d2 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/BaseBlock.java +++ b/src/main/java/com/sk89q/worldedit/blocks/BaseBlock.java @@ -24,37 +24,49 @@ import com.sk89q.jnbt.StringTag; import com.sk89q.jnbt.Tag; import com.sk89q.worldedit.CuboidClipboard.FlipDirection; import com.sk89q.worldedit.foundation.Block; -import com.sk89q.worldedit.world.DataException; +import com.sk89q.worldedit.function.mask.Mask; +import com.sk89q.worldedit.world.registry.WorldData; +import javax.annotation.Nullable; import java.util.Collection; /** - * Represents a mutable copy of a block that is not tied to any 'real' block in a world. - * A single instance of this can be set to multiple locations and each location would - * have a copy of this instance's data. - *

- * Implementations can and should extend this class to allow native implementations - * of NBT data handling, primarily for performance reasons. Subclasses can only convert - * from and to WorldEdit-native NBT structures when absolutely necessary (a.k.a. when - * {@link #getNbtData()} and {@link #setNbtData(CompoundTag)} are called). When - * overriding the NBT methods, {@link #getNbtId()} should be overridden too, otherwise - * the default implementation will invoke {@link #getNbtData()}, a potentially costly - * operation when it is not needed. Implementations may want to cache converted NBT data - * structures if possible. + * Represents a mutable "snapshot" of a block. + * + *

An instance of this block contains all the information needed to + * accurately reproduce the block, provided that the instance was + * made correctly. In some implementations, it may not be possible to get a + * snapshot of blocks correctly, so, for example, the NBT data for a block + * may be missing.

+ * + *

This class identifies blocks using an integer ID. However, IDs for + * a given block may differ between worlds so it is important that users of + * this class convert the ID from one "world space" to another "world space," + * a task that that is assisted with by working with the source and + * destination {@link WorldData} instances. Numeric IDs are utilized because + * they are more space efficient to store, and it also implies that internal + * uses of this class (i.e. history, etc.) do not need to worry about + * interning block string IDs.

+ * + *

A peculiar detail of this class is that it accepts {@code -1} as a + * valid data value. This is due to legacy reasons: WorldEdit uses -1 + * as a "wildcard" block value, even though a {@link Mask} would be + * more appropriate.

*/ public class BaseBlock extends Block implements TileEntityBlock { /** - * Indicates the highest possible block ID (inclusive) that can be used. This value - * is subject to change depending on the implementation, but internally this class - * only supports a range of 4096 IDs (for space reasons), which coincides with the - * number of possible IDs that official Minecraft supports as of version 1.3. + * Indicates the highest possible block ID (inclusive) that can be used. + * This value is subject to change depending on the implementation, but + * internally this class only supports a range of 4096 IDs (for space + * reasons), which coincides with the number of possible IDs that official + * Minecraft supports as of version 1.7. */ public static final int MAX_ID = 4095; /** - * Indicates the maximum data value (inclusive) that can be used. Minecraft 1.4 may - * abolish usage of data values and this value may be removed in the future. + * Indicates the maximum data value (inclusive) that can be used. A future + * version of Minecraft may abolish block data values. */ public static final int MAX_DATA = 15; @@ -63,6 +75,7 @@ public class BaseBlock extends Block implements TileEntityBlock { private short id; private short data; + @Nullable private CompoundTag nbtData; /** @@ -90,17 +103,13 @@ public class BaseBlock extends Block implements TileEntityBlock { } /** - * Construct a block with the given ID, data value, and NBT data structure. + * Construct a block with the given ID, data value and NBT data structure. * * @param id ID value * @param data data value - * @param nbtData NBT data - * @throws DataException if possibly the data is invalid - * @see #setId(int) - * @see #setData(int) - * @see #setNbtData(CompoundTag) + * @param nbtData NBT data, which may be null */ - public BaseBlock(int id, int data, CompoundTag nbtData) { + public BaseBlock(int id, int data, @Nullable CompoundTag nbtData) { setId(id); setData(data); setNbtData(nbtData); @@ -236,11 +245,13 @@ public class BaseBlock extends Block implements TileEntityBlock { } } + @Nullable @Override public CompoundTag getNbtData() { return nbtData; } + @Nullable @Override public void setNbtData(CompoundTag nbtData) { this.nbtData = nbtData; @@ -275,9 +286,11 @@ public class BaseBlock extends Block implements TileEntityBlock { /** * Rotate this block 90 degrees. - * + * * @return new data value + * @deprecated Use {@link BlockData#rotate90(int, int)} */ + @Deprecated public int rotate90() { int newData = BlockData.rotate90(getType(), getData()); setData(newData); @@ -288,7 +301,9 @@ public class BaseBlock extends Block implements TileEntityBlock { * Rotate this block -90 degrees. * * @return new data value + * @deprecated Use {@link BlockData#rotate90Reverse(int, int)} */ + @Deprecated public int rotate90Reverse() { int newData = BlockData.rotate90Reverse(getType(), getData()); setData((short) newData); @@ -300,7 +315,9 @@ public class BaseBlock extends Block implements TileEntityBlock { * * @param increment 1 for forward, -1 for backward * @return new data value + * @deprecated Use {@link BlockData#cycle(int, int, int)} */ + @Deprecated public int cycleData(int increment) { int newData = BlockData.cycle(getType(), getData(), increment); setData((short) newData); @@ -311,7 +328,9 @@ public class BaseBlock extends Block implements TileEntityBlock { * Flip this block. * * @return this block + * @deprecated Use {@link BlockData#flip(int, int)} */ + @Deprecated public BaseBlock flip() { setData((short) BlockData.flip(getType(), getData())); return this; @@ -322,7 +341,9 @@ public class BaseBlock extends Block implements TileEntityBlock { * * @param direction direction to flip in * @return this block + * @deprecated Use {@link BlockData#flip(int, int, FlipDirection)} */ + @Deprecated public BaseBlock flip(FlipDirection direction) { setData((short) BlockData.flip(getType(), getData(), direction)); return this; @@ -356,8 +377,6 @@ public class BaseBlock extends Block implements TileEntityBlock { } /** - * @param iter - * @return * @deprecated This method is silly, use {@link #containsFuzzy(java.util.Collection, BaseBlock)} instead. */ @Deprecated @@ -370,14 +389,12 @@ public class BaseBlock extends Block implements TileEntityBlock { return false; } + /** + * @deprecated Use {@link Blocks#containsFuzzy(Collection, BaseBlock)} + */ + @Deprecated public static boolean containsFuzzy(Collection collection, BaseBlock o) { - // allow masked data in the searchBlocks to match various types - for (BaseBlock b : collection) { - if (b.equalsFuzzy(o)) { - return true; - } - } - return false; + return Blocks.containsFuzzy(collection, o); } @Override diff --git a/src/main/java/com/sk89q/worldedit/blocks/BaseItem.java b/src/main/java/com/sk89q/worldedit/blocks/BaseItem.java index 7ac9fe824..24a2f5be1 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/BaseItem.java +++ b/src/main/java/com/sk89q/worldedit/blocks/BaseItem.java @@ -23,10 +23,10 @@ import java.util.HashMap; import java.util.Map; /** - * Represents an item, without an amount value. See {@link BaseItemStack} for an instance - * with stack amount information. + * Represents an item, without an amount value. See {@link BaseItemStack} + * for an instance with stack amount information. * - * @author sk89q + *

This class may be removed in the future.

*/ public class BaseItem { diff --git a/src/main/java/com/sk89q/worldedit/blocks/BaseItemStack.java b/src/main/java/com/sk89q/worldedit/blocks/BaseItemStack.java index eda3726ea..320fc1b40 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/BaseItemStack.java +++ b/src/main/java/com/sk89q/worldedit/blocks/BaseItemStack.java @@ -22,12 +22,10 @@ package com.sk89q.worldedit.blocks; /** * Represents a stack of BaseItems. * - * @author sk89q + *

This class may be removed in the future.

*/ public class BaseItemStack extends BaseItem { - /** - * Amount of an item. - */ + private int amount = 1; /** diff --git a/src/main/java/com/sk89q/worldedit/blocks/BlockData.java b/src/main/java/com/sk89q/worldedit/blocks/BlockData.java index 815ef38c9..8ff768d2d 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/BlockData.java +++ b/src/main/java/com/sk89q/worldedit/blocks/BlockData.java @@ -23,8 +23,6 @@ import com.sk89q.worldedit.CuboidClipboard.FlipDirection; /** * Block data related classes. - * - * @author sk89q */ public final class BlockData { @@ -34,9 +32,9 @@ public final class BlockData { /** * Rotate a block's data value 90 degrees (north->east->south->west->north); * - * @param type - * @param data - * @return + * @param type the type ID of the bock + * @param data the data ID of the block + * @return the new data value */ public static int rotate90(int type, int data) { switch (type) { @@ -251,10 +249,10 @@ public final class BlockData { /** * Rotate a block's data value -90 degrees (north<-east<-south<-west<-north); - * - * @param type - * @param data - * @return + * + * @param type the type ID of the bock + * @param data the data ID of the block + * @return the new data value */ public static int rotate90Reverse(int type, int data) { // case ([0-9]+): return ([0-9]+) -> case \2: return \1 @@ -470,10 +468,10 @@ public final class BlockData { /** * Flip a block's data value. - * - * @param type - * @param data - * @return + * + * @param type the type ID of the bock + * @param data the data ID of the block + * @return the new data value */ public static int flip(int type, int data) { return rotate90(type, rotate90(type, data)); @@ -481,11 +479,11 @@ public final class BlockData { /** * Flip a block's data value. - * - * @param type - * @param data - * @param direction - * @return + * + * @param type the type ID of the bock + * @param data the data ID of the block + * @param direction the direction to flip + * @return the new data value */ public static int flip(int type, int data, FlipDirection direction) { int flipX = 0; @@ -970,14 +968,6 @@ public final class BlockData { } } - /** - * Better modulo, not just remainder. - */ - private static int mod(int x, int y) { - int res = x % y; - return res < 0 ? res + y : res; - } - /** * Returns the data value for the next color of cloth in the rainbow. This * should not be used if you want to just increment the data value. @@ -1010,8 +1000,9 @@ public final class BlockData { /** * Returns the data value for the previous ext color of cloth in the rainbow. * This should not be used if you want to just increment the data value. - * @param data - * @return + * + * @param data the data value + * @return the new data value */ public static int prevClothColor(int data) { switch (data) { @@ -1035,4 +1026,13 @@ public final class BlockData { return ClothColor.ID.WHITE; } + + /** + * Better modulo, not just remainder. + */ + private static int mod(int x, int y) { + int res = x % y; + return res < 0 ? res + y : res; + } + } diff --git a/src/main/java/com/sk89q/worldedit/blocks/BlockType.java b/src/main/java/com/sk89q/worldedit/blocks/BlockType.java index e7f46f821..0b4e662f8 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/BlockType.java +++ b/src/main/java/com/sk89q/worldedit/blocks/BlockType.java @@ -22,7 +22,15 @@ package com.sk89q.worldedit.blocks; import com.sk89q.util.StringUtil; import com.sk89q.worldedit.PlayerDirection; -import java.util.*; +import javax.annotation.Nullable; +import java.util.EnumSet; +import java.util.HashMap; +import java.util.HashSet; +import java.util.Map; +import java.util.Random; +import java.util.Set; + +import static com.google.common.base.Preconditions.checkNotNull; /** * Block types. @@ -229,8 +237,9 @@ public enum BlockType { /** * Construct the type. * - * @param id - * @param name + * @param id the ID of the block + * @param name the name of the block + * @param lookupKey a name to reference the block by */ BlockType(int id, String name, String lookupKey) { this.id = id; @@ -241,8 +250,9 @@ public enum BlockType { /** * Construct the type. * - * @param id - * @param name + * @param id the ID of the block + * @param name the name of the block + * @param lookupKeys an array of keys to reference the block by */ BlockType(int id, String name, String... lookupKeys) { this.id = id; @@ -253,9 +263,10 @@ public enum BlockType { /** * Return type from ID. May return null. * - * @param id - * @return + * @param id the type ID + * @return a block type, otherwise null */ + @Nullable public static BlockType fromID(int id) { return ids.get(id); } @@ -263,9 +274,10 @@ public enum BlockType { /** * Return type from name. May return null. * - * @param name - * @return + * @param name the name to search + * @return a block type or null */ + @Nullable public static BlockType lookup(String name) { return lookup(name, true); } @@ -273,10 +285,11 @@ public enum BlockType { /** * Return type from name. May return null. * - * @param name - * @param fuzzy - * @return + * @param name the name (or ID) of a block + * @param fuzzy true to for a fuzzy search on the block name + * @return a block type or null */ + @Nullable public static BlockType lookup(String name, boolean fuzzy) { try { return fromID(Integer.parseInt(name)); @@ -285,8 +298,8 @@ public enum BlockType { } } - private static Map itemBlockMapping = new HashMap(); - private static Map dataItemBlockMapping = new HashMap(); + private static final Map itemBlockMapping = new HashMap(); + private static final Map dataItemBlockMapping = new HashMap(); static { for (int data = 0; data < 16; ++data) { dataItemBlockMapping.put(typeDataKey(BlockID.DIRT, data), new BaseBlock(BlockID.DIRT, data)); @@ -328,6 +341,14 @@ public enum BlockType { itemBlockMapping.put(ItemID.COMPARATOR, new BaseBlock(BlockID.COMPARATOR_OFF, -1)); } + /** + * Get the equivalent block for an item. + * + * @param typeId the type ID of the block + * @param data the data valuie of the block + * @return a block or null + */ + @Nullable public static BaseBlock getBlockForItem(int typeId, int data) { final BaseBlock block = itemBlockMapping.get(typeId); @@ -341,7 +362,7 @@ public enum BlockType { /** * Get block numeric ID. * - * @return + * @return the block ID */ public int getID() { return id; @@ -350,7 +371,7 @@ public enum BlockType { /** * Get user-friendly block name. * - * @return + * @return the block name */ public String getName() { return name; @@ -415,19 +436,21 @@ public enum BlockType { } /** - * Checks to see whether a block should be placed last. + * Checks to see whether a block should be placed last (when reordering + * blocks that are placed). * - * @param id - * @return + * @param id the block ID + * @return true if the block should be placed last */ public static boolean shouldPlaceLast(int id) { return shouldPlaceLast.contains(id); } /** - * Checks to see whether this block should be placed last. + * Checks to see whether this block should be placed last (when reordering + * blocks that are placed) * - * @return + * @return true if the block should be placed last */ public boolean shouldPlaceLast() { return shouldPlaceLast.contains(id); @@ -454,8 +477,8 @@ public enum BlockType { * * This applies to blocks that can be attached to other blocks that have an attachment. * - * @param id - * @return + * @param id the type ID of the block + * @return whether the block is in the final queue */ public static boolean shouldPlaceFinal(int id) { return shouldPlaceFinal.contains(id); @@ -522,8 +545,8 @@ public enum BlockType { /** * Checks whether a block can be passed through. * - * @param id - * @return + * @param id the ID of the block + * @return true if the block can be passed through */ public static boolean canPassThrough(int id) { return canPassThrough.contains(id); @@ -532,9 +555,9 @@ public enum BlockType { /** * Checks whether a block can be passed through. * - * @param id - * @param data - * @return + * @param id the ID of the block + * @param data the data value of the block + * @return true if the block can be passed through */ public static boolean canPassThrough(int id, int data) { return canPassThrough.contains(-16*id-data) || canPassThrough.contains(id); @@ -543,17 +566,18 @@ public enum BlockType { /** * Checks whether a block can be passed through. * - * @param block - * @return + * @param block the block + * @return true if the block can be passed through */ public static boolean canPassThrough(BaseBlock block) { + checkNotNull(block); return canPassThrough(block.getId(), block.getData()); } /** - * Checks whether a block can be passed through. + * Checks whether the block type can be passed through. * - * @return + * @return whether the block can be passed through */ public boolean canPassThrough() { return canPassThrough.contains(id); @@ -622,9 +646,9 @@ public enum BlockType { /** * Returns the y offset a player falls to when falling onto the top of a block at xp+0.5/zp+0.5. * - * @param id - * @param data - * @return + * @param id the block ID + * @param data the block data value + * @return the y offset */ public static double centralTopLimit(int id, int data) { if (centralTopLimit.containsKey(-16*id-data)) @@ -639,17 +663,18 @@ public enum BlockType { /** * Returns the y offset a player falls to when falling onto the top of a block at xp+0.5/zp+0.5. * - * @param block - * @return + * @param block the block + * @return the y offset */ public static double centralTopLimit(BaseBlock block) { + checkNotNull(block); return centralTopLimit(block.getId(), block.getData()); } /** * Returns the y offset a player falls to when falling onto the top of a block at xp+0.5/zp+0.5. * - * @return + * @return the y offset */ public double centralTopLimit() { if (centralTopLimit.containsKey(id)) @@ -771,8 +796,8 @@ public enum BlockType { /** * Returns true if the block uses its data value. * - * @param id - * @return + * @param id the type ID + * @return true if the block type uses its data value */ public static boolean usesData(int id) { return usesData.contains(id); @@ -781,7 +806,7 @@ public enum BlockType { /** * Returns true if the block uses its data value. * - * @return + * @return true if this block type uses its data value */ public boolean usesData() { return usesData.contains(id); @@ -806,8 +831,8 @@ public enum BlockType { /** * Returns true if the block is a container block. * - * @param id - * @return + * @param id the block ID + * @return true if the block is a container */ public static boolean isContainerBlock(int id) { return isContainerBlock.contains(id); @@ -816,7 +841,7 @@ public enum BlockType { /** * Returns true if the block is a container block. * - * @return + * @return true if the block is a container block */ public boolean isContainerBlock() { return isContainerBlock.contains(id); @@ -861,19 +886,19 @@ public enum BlockType { } /** - * Returns true if a block uses redstone in some way. + * Returns true if a block uses Redstone in some way. * - * @param id - * @return + * @param id the type ID of the block + * @return true if the block uses Redstone */ public static boolean isRedstoneBlock(int id) { return isRedstoneBlock.contains(id); } /** - * Returns true if a block uses redstone in some way. + * Returns true if a block uses Redstone in some way. * - * @return + * @return true if the block uses Redstone */ public boolean isRedstoneBlock() { return isRedstoneBlock.contains(id); @@ -894,21 +919,23 @@ public enum BlockType { } /** - * Returns true if a block can transfer redstone. - * Made this since isRedstoneBlock was getting big. + * Returns true if a block can transfer Redstone. * - * @param id - * @return + *

This was made since {@link #isRedstoneBlock} was getting big.

+ * + * @param id the type ID of the block + * @return true if the block can transfer redstone */ public static boolean canTransferRedstone(int id) { return canTransferRedstone.contains(id); } /** - * Returns true if a block can transfer redstone. - * Made this since isRedstoneBlock was getting big. + * Returns true if a block can transfer Redstone. * - * @return + *

This was made since {@link #isRedstoneBlock} was getting big.

+ * + * @return true if the block can transfer redstone */ public boolean canTransferRedstone() { return canTransferRedstone.contains(id); @@ -935,19 +962,19 @@ public enum BlockType { } /** - * Yay for convenience methods. + * Returns whether the block is a Redstone source. * - * @param id - * @return + * @param id the type ID of the block + * @return true if the block is a Redstone source */ public static boolean isRedstoneSource(int id) { return isRedstoneSource.contains(id); } /** - * Yay for convenience methods. + * Returns whether the block is a Redstone source. * - * @return + * @return true if the block is a Redstone source */ public boolean isRedstoneSource() { return isRedstoneSource.contains(id); @@ -965,19 +992,19 @@ public enum BlockType { } /** - * Checks if the id is that of one of the rail types + * Checks if the block is that of one of the rail types. * - * @param id - * @return + * @param id the type ID of the block + * @return true if the block is a rail block */ public static boolean isRailBlock(int id) { return isRailBlock.contains(id); } /** - * Checks if the id is that of one of the rail types + * Checks if the block is that of one of the rail types * - * @return + * @return true if the block is a rail block */ public boolean isRailBlock() { return isRailBlock.contains(id); @@ -1018,10 +1045,10 @@ public enum BlockType { } /** - * Checks if the block type is naturally occuring + * Checks if the block type is naturally occurring. * - * @param id ID of the block - * @return true if the block type is naturally occuring + * @param id the type ID of the block + * @return true if the block type is naturally occurring * @deprecated Use {@link #isNaturalTerrainBlock(int, int)} */ @Deprecated @@ -1030,30 +1057,30 @@ public enum BlockType { } /** - * Checks if the block type is naturally occuring + * Checks if the block type is naturally occurring * - * @param id ID of the block - * @param data Data value of the block - * @return true if the block type is naturally occuring + * @param id the type ID of the block + * @param data data value of the block + * @return true if the block type is naturally occurring */ public static boolean isNaturalTerrainBlock(int id, int data) { return isNaturalTerrainBlock.contains(-16*id-data) || isNaturalTerrainBlock.contains(id); } /** - * Checks if the block type is naturally occuring + * Checks if the block type is naturally occurring * - * @param block The block - * @return true if the block type is naturally occuring + * @param block the block + * @return true if the block type is naturally occurring */ public static boolean isNaturalTerrainBlock(BaseBlock block) { return isNaturalTerrainBlock(block.getId(), block.getData()); } /** - * Checks if the block type is naturally occuring + * Checks if the block type is naturally occurring * - * @return true if the block type is naturally occuring + * @return true if the block type is naturally occurring */ public boolean isNaturalTerrainBlock() { return isNaturalTerrainBlock.contains(id); @@ -1087,10 +1114,10 @@ public enum BlockType { } /** - * Checks if the block type emits light + * Checks if the block type emits light. * - * @param id - * @return + * @param id the type ID of the block + * @return true if the block emits light */ public static boolean emitsLight(int id) { return emitsLight.contains(id); @@ -1197,10 +1224,10 @@ public enum BlockType { } /** - * Checks if the block type lets light through + * Checks if the block type lets light through. * - * @param id - * @return + * @param id the type ID of the block + * @return true if the block type lets light through */ public static boolean isTranslucent(int id) { return isTranslucent.contains(id); @@ -1409,10 +1436,11 @@ public enum BlockType { * dropped, a block with a BaseItemStack of type AIR and size 0 will be returned. * If the block should not be destroyed (i.e. bedrock), null will be returned. * - * @param type - * @param data - * @return + * @param type the type of of the block + * @param data the data value of the block + * @return the item or null */ + @Nullable public static BaseItem getBlockBagItem(int type, int data) { BaseItem dropped = nonDataBlockBagItems.get(type); if (dropped != null) return dropped; @@ -1445,8 +1473,8 @@ public enum BlockType { * dropped, 0 will be returned. If the block should not be destroyed * (i.e. bedrock), -1 will be returned. * - * @param id - * @return + * @param id the type ID of the block + * @return the dropped item * @deprecated This function ignores the data value. */ @Deprecated @@ -1458,11 +1486,26 @@ public enum BlockType { return dropped.getType(); } + /** + * Get the block drop for this type given a data value. + * + * @param data the data value + * @return the item stack + */ public BaseItemStack getBlockDrop(short data) { return getBlockDrop(id, data); } private static final Random random = new Random(); + + /** + * Get the block drop for a block. + * + * @param id the type ID of the block + * @param data the data value + * @return an item or null + */ + @Nullable public static BaseItemStack getBlockDrop(int id, short data) { int store; switch (id) { @@ -1765,8 +1808,8 @@ public enum BlockType { * Returns the direction to the block(B) this block(A) is attached to. * Attached means that if block B is destroyed, block A will pop off. * - * @param type The block id of block A - * @param data The data value of block A + * @param type the block id of block A + * @param data the data value of block A * @return direction to block B */ public static PlayerDirection getAttachment(int type, int data) { diff --git a/src/main/java/com/sk89q/worldedit/blocks/Blocks.java b/src/main/java/com/sk89q/worldedit/blocks/Blocks.java new file mode 100644 index 000000000..c4c3c7f48 --- /dev/null +++ b/src/main/java/com/sk89q/worldedit/blocks/Blocks.java @@ -0,0 +1,49 @@ +/* + * WorldEdit, a Minecraft world manipulation toolkit + * Copyright (C) sk89q + * Copyright (C) WorldEdit team and contributors + * + * This program is free software: you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as published by the + * Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + * for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . + */ + +package com.sk89q.worldedit.blocks; + +import java.util.Collection; + +/** + * Block-related utility methods. + */ +public final class Blocks { + + private Blocks() { + } + + /** + * Checks whether a given block is in a list of base blocks. + * + * @param collection the collection + * @param o the block + * @return true if the collection contains the given block + */ + public static boolean containsFuzzy(Collection collection, BaseBlock o) { + // Allow masked data in the searchBlocks to match various types + for (BaseBlock b : collection) { + if (b.equalsFuzzy(o)) { + return true; + } + } + return false; + } + +} diff --git a/src/main/java/com/sk89q/worldedit/blocks/ClothColor.java b/src/main/java/com/sk89q/worldedit/blocks/ClothColor.java index 5336e2e8f..76e362e7f 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/ClothColor.java +++ b/src/main/java/com/sk89q/worldedit/blocks/ClothColor.java @@ -19,16 +19,18 @@ package com.sk89q.worldedit.blocks; +import javax.annotation.Nullable; import java.util.Map; import java.util.HashMap; import java.util.EnumSet; /** - * Cloth colors. + * The colors for wool. * - * @author sk89q + *

This class may be removed in the future.

*/ public enum ClothColor { + WHITE(ID.WHITE, "White", "white"), ORANGE(ID.ORANGE, "Orange", "orange"), MAGENTA(ID.MAGENTA, "Magenta", "magenta"), @@ -63,6 +65,9 @@ public enum ClothColor { public static final int DARK_GREEN = 13; public static final int RED = 14; public static final int BLACK = 15; + + private ID() { + } } /** @@ -91,8 +96,9 @@ public enum ClothColor { /** * Construct the type. * - * @param id - * @param name + * @param id the ID of the color + * @param name the name of the color + * @param lookupKey a name to refer to the color by */ ClothColor(int id, String name, String lookupKey) { this.id = id; @@ -103,8 +109,9 @@ public enum ClothColor { /** * Construct the type. * - * @param id - * @param name + * @param id the ID of the color + * @param name the name of the color + * @param lookupKeys an array of lookup keys */ ClothColor(int id, String name, String[] lookupKeys) { this.id = id; @@ -115,9 +122,10 @@ public enum ClothColor { /** * Return type from ID. May return null. * - * @param id - * @return + * @param id the ID + * @return a color or null */ + @Nullable public static ClothColor fromID(int id) { return ids.get(id); } @@ -125,9 +133,10 @@ public enum ClothColor { /** * Return type from name. May return null. * - * @param name - * @return + * @param name the name of the color + * @return a color or null */ + @Nullable public static ClothColor lookup(String name) { return lookup.get(name.toLowerCase()); } @@ -135,7 +144,7 @@ public enum ClothColor { /** * Get item numeric ID. * - * @return + * @return the ID */ public int getID() { return id; @@ -144,9 +153,10 @@ public enum ClothColor { /** * Get user-friendly item name. * - * @return + * @return the name */ public String getName() { return name; } + } diff --git a/src/main/java/com/sk89q/worldedit/blocks/ItemID.java b/src/main/java/com/sk89q/worldedit/blocks/ItemID.java index a55cf1536..2777e3c6c 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/ItemID.java +++ b/src/main/java/com/sk89q/worldedit/blocks/ItemID.java @@ -21,10 +21,9 @@ package com.sk89q.worldedit.blocks; /** * List of item IDs. - * - * @author sk89q */ public final class ItemID { + public static final int IRON_SHOVEL = 256; public static final int IRON_PICK = 257; public static final int IRON_AXE = 258; @@ -202,4 +201,5 @@ public final class ItemID { private ItemID() { } + } diff --git a/src/main/java/com/sk89q/worldedit/blocks/ItemType.java b/src/main/java/com/sk89q/worldedit/blocks/ItemType.java index 21d0f6bfa..94413ff96 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/ItemType.java +++ b/src/main/java/com/sk89q/worldedit/blocks/ItemType.java @@ -19,6 +19,9 @@ package com.sk89q.worldedit.blocks; +import com.sk89q.util.StringUtil; + +import javax.annotation.Nullable; import java.util.EnumSet; import java.util.HashMap; import java.util.HashSet; @@ -26,14 +29,11 @@ import java.util.LinkedHashMap; import java.util.Map; import java.util.Set; -import com.sk89q.util.StringUtil; - /** - * ItemType types. - * - * @author sk89q + * An enum of types of items. */ public enum ItemType { + // Blocks AIR(BlockID.AIR, "Air", "air"), STONE(BlockID.STONE, "Stone", "stone", "rock"), @@ -412,8 +412,9 @@ public enum ItemType { /** * Construct the type. * - * @param id - * @param name + * @param id the type ID of the item + * @param name the name of the item + * @param lookupKey a name to refer to the item type by */ ItemType(int id, String name, String lookupKey) { this.id = id; @@ -424,8 +425,9 @@ public enum ItemType { /** * Construct the type. * - * @param id - * @param name + * @param id the type ID of the item + * @param name the name of the item + * @param lookupKeys a list of names to refer to the item type by */ ItemType(int id, String name, String... lookupKeys) { this.id = id; @@ -436,9 +438,10 @@ public enum ItemType { /** * Return type from ID. May return null. * - * @param id - * @return + * @param id the type ID of the item + * @return an item type or null */ + @Nullable public static ItemType fromID(int id) { return ids.get(id); } @@ -446,8 +449,10 @@ public enum ItemType { /** * Get a name for the item. * - * @param id - * @return + *

If the item type is not null, the numeric ID will be returned.

+ * + * @param id the type ID of the item + * @return a name for the item */ public static String toName(int id) { ItemType type = ids.get(id); @@ -461,8 +466,10 @@ public enum ItemType { /** * Get a name for a held item. * - * @param id - * @return + *

If the item type is not null, the numeric ID will be returned.

+ * + * @param id the type ID of the item + * @return the name of the item */ public static String toHeldName(int id) { if (id == 0) { @@ -479,9 +486,10 @@ public enum ItemType { /** * Return type from name. May return null. * - * @param name - * @return + * @param name the name + * @return the type or null */ + @Nullable public static ItemType lookup(String name) { return lookup(name, true); } @@ -489,10 +497,11 @@ public enum ItemType { /** * Return type from name. May return null. * - * @param name - * @param fuzzy - * @return + * @param name the name + * @param fuzzy true to do a fuzzy string search + * @return the type or null */ + @Nullable public static ItemType lookup(String name, boolean fuzzy) { try { return fromID(Integer.parseInt(name)); @@ -504,7 +513,7 @@ public enum ItemType { /** * Get item numeric ID. * - * @return + * @return the type ID of this item */ public int getID() { return id; @@ -513,7 +522,7 @@ public enum ItemType { /** * Get user-friendly item name. * - * @return + * @return a name of this item */ public String getName() { return name; @@ -522,7 +531,7 @@ public enum ItemType { /** * Get a list of aliases. * - * @return + * @return a list of aliases */ public String[] getAliases() { return lookupKeys; @@ -620,8 +629,8 @@ public enum ItemType { /** * Returns true if an item should not be stacked. * - * @param id - * @return + * @param id the type ID of the item + * @return true if the item should not stack */ public static boolean shouldNotStack(int id) { return shouldNotStack.contains(id); @@ -668,10 +677,11 @@ public enum ItemType { * Returns true if an item uses its damage value for something * other than damage. * - * @param id - * @return + * @param id the type ID of the item + * @return true if the item uses its damage value */ public static boolean usesDamageValue(int id) { return usesDamageValue.contains(id); } + } diff --git a/src/main/java/com/sk89q/worldedit/blocks/TileEntityBlock.java b/src/main/java/com/sk89q/worldedit/blocks/TileEntityBlock.java index af0c86bb7..3c67bf0e8 100644 --- a/src/main/java/com/sk89q/worldedit/blocks/TileEntityBlock.java +++ b/src/main/java/com/sk89q/worldedit/blocks/TileEntityBlock.java @@ -22,11 +22,10 @@ package com.sk89q.worldedit.blocks; import com.sk89q.worldedit.world.NbtValued; /** - * Indicates a block that contains extra data identified as an NBT structure. Compared - * to a {@link NbtValued}, tile entity blocks also contain an ID. + * Indicates a block that contains extra data identified as an NBT structure. + * Compared to a {@link NbtValued}, tile entity blocks also contain an ID. * * @see NbtValued - * @author sk89q */ public interface TileEntityBlock extends NbtValued { diff --git a/src/main/java/com/sk89q/worldedit/function/mask/FuzzyBlockMask.java b/src/main/java/com/sk89q/worldedit/function/mask/FuzzyBlockMask.java index e7f247c94..19a0b7590 100644 --- a/src/main/java/com/sk89q/worldedit/function/mask/FuzzyBlockMask.java +++ b/src/main/java/com/sk89q/worldedit/function/mask/FuzzyBlockMask.java @@ -19,9 +19,10 @@ package com.sk89q.worldedit.function.mask; -import com.sk89q.worldedit.extent.Extent; import com.sk89q.worldedit.Vector; import com.sk89q.worldedit.blocks.BaseBlock; +import com.sk89q.worldedit.blocks.Blocks; +import com.sk89q.worldedit.extent.Extent; import java.util.Collection; @@ -41,6 +42,6 @@ public class FuzzyBlockMask extends BlockMask { Collection blocks = getBlocks(); BaseBlock lazyBlock = extent.getLazyBlock(vector); BaseBlock compare = new BaseBlock(lazyBlock.getType(), lazyBlock.getData()); - return BaseBlock.containsFuzzy(blocks, compare); + return Blocks.containsFuzzy(blocks, compare); } }