001 package org.bukkit.block;
002
003 import java.util.Collection;
004
005 import org.bukkit.Chunk;
006 import org.bukkit.Material;
007 import org.bukkit.World;
008 import org.bukkit.Location;
009 import org.bukkit.inventory.ItemStack;
010 import org.bukkit.metadata.Metadatable;
011
012 /**
013 * Represents a block. This is a live object, and only one Block may exist for
014 * any given location in a world. The state of the block may change
015 * concurrently to your own handling of it; use block.getState() to get a
016 * snapshot state of a block which will not be modified.
017 */
018 public interface Block extends Metadatable {
019
020 /**
021 * Gets the metadata for this block
022 *
023 * @return block specific metadata
024 * @deprecated Magic value
025 */
026 @Deprecated
027 byte getData();
028
029 /**
030 * Gets the block at the given offsets
031 *
032 * @param modX X-coordinate offset
033 * @param modY Y-coordinate offset
034 * @param modZ Z-coordinate offset
035 * @return Block at the given offsets
036 */
037 Block getRelative(int modX, int modY, int modZ);
038
039 /**
040 * Gets the block at the given face
041 * <p>
042 * This method is equal to getRelative(face, 1)
043 *
044 * @param face Face of this block to return
045 * @return Block at the given face
046 * @see #getRelative(BlockFace, int)
047 */
048 Block getRelative(BlockFace face);
049
050 /**
051 * Gets the block at the given distance of the given face
052 * <p>
053 * For example, the following method places water at 100,102,100; two
054 * blocks above 100,100,100.
055 *
056 * <pre>
057 * Block block = world.getBlockAt(100, 100, 100);
058 * Block shower = block.getRelative(BlockFace.UP, 2);
059 * shower.setType(Material.WATER);
060 * </pre>
061 *
062 * @param face Face of this block to return
063 * @param distance Distance to get the block at
064 * @return Block at the given face
065 */
066 Block getRelative(BlockFace face, int distance);
067
068 /**
069 * Gets the type of this block
070 *
071 * @return block type
072 */
073 Material getType();
074
075 /**
076 * Gets the type-id of this block
077 *
078 * @return block type-id
079 * @deprecated Magic value
080 */
081 @Deprecated
082 int getTypeId();
083
084 /**
085 * Gets the light level between 0-15
086 *
087 * @return light level
088 */
089 byte getLightLevel();
090
091 /**
092 * Get the amount of light at this block from the sky.
093 * <p>
094 * Any light given from other sources (such as blocks like torches) will
095 * be ignored.
096 *
097 * @return Sky light level
098 */
099 byte getLightFromSky();
100
101 /**
102 * Get the amount of light at this block from nearby blocks.
103 * <p>
104 * Any light given from other sources (such as the sun) will be ignored.
105 *
106 * @return Block light level
107 */
108 byte getLightFromBlocks();
109
110 /**
111 * Gets the world which contains this Block
112 *
113 * @return World containing this block
114 */
115 World getWorld();
116
117 /**
118 * Gets the x-coordinate of this block
119 *
120 * @return x-coordinate
121 */
122 int getX();
123
124 /**
125 * Gets the y-coordinate of this block
126 *
127 * @return y-coordinate
128 */
129 int getY();
130
131 /**
132 * Gets the z-coordinate of this block
133 *
134 * @return z-coordinate
135 */
136 int getZ();
137
138 /**
139 * Gets the Location of the block
140 *
141 * @return Location of block
142 */
143 Location getLocation();
144
145 /**
146 * Stores the location of the block in the provided Location object.
147 * <p>
148 * If the provided Location is null this method does nothing and returns
149 * null.
150 *
151 * @return The Location object provided or null
152 */
153 Location getLocation(Location loc);
154
155 /**
156 * Gets the chunk which contains this block
157 *
158 * @return Containing Chunk
159 */
160 Chunk getChunk();
161
162 /**
163 * Sets the metadata for this block
164 *
165 * @param data New block specific metadata
166 * @deprecated Magic value
167 */
168 @Deprecated
169 void setData(byte data);
170
171 /**
172 * Sets the metadata for this block
173 *
174 * @param data New block specific metadata
175 * @param applyPhysics False to cancel physics from the changed block.
176 * @deprecated Magic value
177 */
178 @Deprecated
179 void setData(byte data, boolean applyPhysics);
180
181 /**
182 * Sets the type of this block
183 *
184 * @param type Material to change this block to
185 */
186 void setType(Material type);
187
188 /**
189 * Sets the type-id of this block
190 *
191 * @param type Type-Id to change this block to
192 * @return whether the block was changed
193 * @deprecated Magic value
194 */
195 @Deprecated
196 boolean setTypeId(int type);
197
198 /**
199 * Sets the type-id of this block
200 *
201 * @param type Type-Id to change this block to
202 * @param applyPhysics False to cancel physics on the changed block.
203 * @return whether the block was changed
204 * @deprecated Magic value
205 */
206 @Deprecated
207 boolean setTypeId(int type, boolean applyPhysics);
208
209 /**
210 * Sets the type-id of this block
211 *
212 * @param type Type-Id to change this block to
213 * @param data The data value to change this block to
214 * @param applyPhysics False to cancel physics on the changed block
215 * @return whether the block was changed
216 * @deprecated Magic value
217 */
218 @Deprecated
219 boolean setTypeIdAndData(int type, byte data, boolean applyPhysics);
220
221 /**
222 * Gets the face relation of this block compared to the given block
223 * <p>
224 * For example:
225 * <pre>
226 * Block current = world.getBlockAt(100, 100, 100);
227 * Block target = world.getBlockAt(100, 101, 100);
228 *
229 * current.getFace(target) == BlockFace.Up;
230 * </pre>
231 * <br />
232 * If the given block is not connected to this block, null may be returned
233 *
234 * @param block Block to compare against this block
235 * @return BlockFace of this block which has the requested block, or null
236 */
237 BlockFace getFace(Block block);
238
239 /**
240 * Captures the current state of this block. You may then cast that state
241 * into any accepted type, such as Furnace or Sign.
242 * <p>
243 * The returned object will never be updated, and you are not guaranteed
244 * that (for example) a sign is still a sign after you capture its state.
245 *
246 * @return BlockState with the current state of this block.
247 */
248 BlockState getState();
249
250 /**
251 * Returns the biome that this block resides in
252 *
253 * @return Biome type containing this block
254 */
255 Biome getBiome();
256
257 /**
258 * Sets the biome that this block resides in
259 *
260 * @param bio new Biome type for this block
261 */
262 void setBiome(Biome bio);
263
264 /**
265 * Returns true if the block is being powered by Redstone.
266 *
267 * @return True if the block is powered.
268 */
269 boolean isBlockPowered();
270
271 /**
272 * Returns true if the block is being indirectly powered by Redstone.
273 *
274 * @return True if the block is indirectly powered.
275 */
276 boolean isBlockIndirectlyPowered();
277
278 /**
279 * Returns true if the block face is being powered by Redstone.
280 *
281 * @param face The block face
282 * @return True if the block face is powered.
283 */
284 boolean isBlockFacePowered(BlockFace face);
285
286 /**
287 * Returns true if the block face is being indirectly powered by Redstone.
288 *
289 * @param face The block face
290 * @return True if the block face is indirectly powered.
291 */
292 boolean isBlockFaceIndirectlyPowered(BlockFace face);
293
294 /**
295 * Returns the redstone power being provided to this block face
296 *
297 * @param face the face of the block to query or BlockFace.SELF for the
298 * block itself
299 * @return The power level.
300 */
301 int getBlockPower(BlockFace face);
302
303 /**
304 * Returns the redstone power being provided to this block
305 *
306 * @return The power level.
307 */
308 int getBlockPower();
309
310 /**
311 * Checks if this block is empty.
312 * <p>
313 * A block is considered empty when {@link #getType()} returns {@link
314 * Material#AIR}.
315 *
316 * @return true if this block is empty
317 */
318 boolean isEmpty();
319
320 /**
321 * Checks if this block is liquid.
322 * <p>
323 * A block is considered liquid when {@link #getType()} returns {@link
324 * Material#WATER}, {@link Material#STATIONARY_WATER}, {@link
325 * Material#LAVA} or {@link Material#STATIONARY_LAVA}.
326 *
327 * @return true if this block is liquid
328 */
329 boolean isLiquid();
330
331 /**
332 * Gets the temperature of the biome of this block
333 *
334 * @return Temperature of this block
335 */
336 double getTemperature();
337
338 /**
339 * Gets the humidity of the biome of this block
340 *
341 * @return Humidity of this block
342 */
343 double getHumidity();
344
345 /**
346 * Returns the reaction of the block when moved by a piston
347 *
348 * @return reaction
349 */
350 PistonMoveReaction getPistonMoveReaction();
351
352 /**
353 * Breaks the block and spawns items as if a player had digged it
354 *
355 * @return true if the block was destroyed
356 */
357 boolean breakNaturally();
358
359 /**
360 * Breaks the block and spawns items as if a player had digged it with a
361 * specific tool
362 *
363 * @param tool The tool or item in hand used for digging
364 * @return true if the block was destroyed
365 */
366 boolean breakNaturally(ItemStack tool);
367
368 /**
369 * Returns a list of items which would drop by destroying this block
370 *
371 * @return a list of dropped items for this type of block
372 */
373 Collection<ItemStack> getDrops();
374
375 /**
376 * Returns a list of items which would drop by destroying this block with
377 * a specific tool
378 *
379 * @param tool The tool or item in hand used for digging
380 * @return a list of dropped items for this type of block
381 */
382 Collection<ItemStack> getDrops(ItemStack tool);
383
384 }