001 package org.bukkit.block;
002
003 import org.bukkit.Chunk;
004 import org.bukkit.Location;
005 import org.bukkit.Material;
006 import org.bukkit.World;
007 import org.bukkit.material.MaterialData;
008 import org.bukkit.metadata.Metadatable;
009
010 /**
011 * Represents a captured state of a block, which will not change
012 * automatically.
013 * <p>
014 * Unlike Block, which only one object can exist per coordinate, BlockState
015 * can exist multiple times for any given Block. Note that another plugin may
016 * change the state of the block and you will not know, or they may change the
017 * block to another type entirely, causing your BlockState to become invalid.
018 */
019 public interface BlockState extends Metadatable {
020
021 /**
022 * Gets the block represented by this BlockState
023 *
024 * @return Block that this BlockState represents
025 */
026 Block getBlock();
027
028 /**
029 * Gets the metadata for this block
030 *
031 * @return block specific metadata
032 */
033 MaterialData getData();
034
035 /**
036 * Gets the type of this block
037 *
038 * @return block type
039 */
040 Material getType();
041
042 /**
043 * Gets the type-id of this block
044 *
045 * @return block type-id
046 * @deprecated Magic value
047 */
048 @Deprecated
049 int getTypeId();
050
051 /**
052 * Gets the light level between 0-15
053 *
054 * @return light level
055 */
056 byte getLightLevel();
057
058 /**
059 * Gets the world which contains this Block
060 *
061 * @return World containing this block
062 */
063 World getWorld();
064
065 /**
066 * Gets the x-coordinate of this block
067 *
068 * @return x-coordinate
069 */
070 int getX();
071
072 /**
073 * Gets the y-coordinate of this block
074 *
075 * @return y-coordinate
076 */
077 int getY();
078
079 /**
080 * Gets the z-coordinate of this block
081 *
082 * @return z-coordinate
083 */
084 int getZ();
085
086 /**
087 * Gets the location of this block
088 *
089 * @return location
090 */
091 Location getLocation();
092
093 /**
094 * Stores the location of this block in the provided Location object.
095 * <p>
096 * If the provided Location is null this method does nothing and returns
097 * null.
098 *
099 * @return The Location object provided or null
100 */
101 Location getLocation(Location loc);
102
103 /**
104 * Gets the chunk which contains this block
105 *
106 * @return Containing Chunk
107 */
108 Chunk getChunk();
109
110 /**
111 * Sets the metadata for this block
112 *
113 * @param data New block specific metadata
114 */
115 void setData(MaterialData data);
116
117 /**
118 * Sets the type of this block
119 *
120 * @param type Material to change this block to
121 */
122 void setType(Material type);
123
124 /**
125 * Sets the type-id of this block
126 *
127 * @param type Type-Id to change this block to
128 * @return Whether it worked?
129 * @deprecated Magic value
130 */
131 @Deprecated
132 boolean setTypeId(int type);
133
134 /**
135 * Attempts to update the block represented by this state, setting it to
136 * the new values as defined by this state.
137 * <p>
138 * This has the same effect as calling update(false). That is to say,
139 * this will not modify the state of a block if it is no longer the same
140 * type as it was when this state was taken. It will return false in this
141 * eventuality.
142 *
143 * @return true if the update was successful, otherwise false
144 * @see #update(boolean)
145 */
146 boolean update();
147
148 /**
149 * Attempts to update the block represented by this state, setting it to
150 * the new values as defined by this state.
151 * <p>
152 * This has the same effect as calling update(force, true). That is to
153 * say, this will trigger a physics update to surrounding blocks.
154 *
155 * @param force true to forcefully set the state
156 * @return true if the update was successful, otherwise false
157 */
158 boolean update(boolean force);
159
160 /**
161 * Attempts to update the block represented by this state, setting it to
162 * the new values as defined by this state.
163 * <p>
164 * Unless force is true, this will not modify the state of a block if it
165 * is no longer the same type as it was when this state was taken. It will
166 * return false in this eventuality.
167 * <p>
168 * If force is true, it will set the type of the block to match the new
169 * state, set the state data and then return true.
170 * <p>
171 * If applyPhysics is true, it will trigger a physics update on
172 * surrounding blocks which could cause them to update or disappear.
173 *
174 * @param force true to forcefully set the state
175 * @param applyPhysics false to cancel updating physics on surrounding
176 * blocks
177 * @return true if the update was successful, otherwise false
178 */
179 boolean update(boolean force, boolean applyPhysics);
180
181 /**
182 * @return The data as a raw byte.
183 * @deprecated Magic value
184 */
185 @Deprecated
186 public byte getRawData();
187
188 /**
189 * @param data The new data value for the block.
190 * @deprecated Magic value
191 */
192 @Deprecated
193 public void setRawData(byte data);
194 }