OpenSource/PaperMC
OpenSource/PaperMC
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-01-02 17:32:03 +01:00
Code Issues Projects Releases Packages Wiki Activity

(Relatively) minor javadoc cleanup

Browse source 
By: Dinnerbone <dinnerbone@dinnerbone.com>
This commit is contained in:
Bukkit/Spigot 2011-02-19 22:47:23 +00:00
parent 314bf387b5
commit 6203fc2652
4 changed files with 275 additions and 111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
paper-api/src/main/java/org/bukkit/ChatColor.java
View file

@ -7,21 +7,69 @@ import java.util.Map;
* All supported color values for chat
*/
public enum ChatColor {
/**
* Represents black
*/
BLACK(0x0),
/**
* Represents dark blue
*/
DARK_BLUE(0x1),
/**
* Represents dark green
*/
DARK_GREEN(0x2),
/**
* Represents dark blue (aqua)
*/
DARK_AQUA(0x3),
/**
* Represents dark red
*/
DARK_RED(0x4),
/**
* Represents dark purple
*/
DARK_PURPLE(0x5),
/**
* Represents gold
*/
GOLD(0x6),
/**
* Represents gray
*/
GRAY(0x7),
/**
* Represents dark gray
*/
DARK_GRAY(0x8),
/**
* Represents blue
*/
BLUE(0x9),
/**
* Represents green
*/
GREEN(0xA),
/**
* Represents aqua
*/
AQUA(0xB),
/**
* Represents red
*/
RED(0xC),
/**
* Represents light purple
*/
LIGHT_PURPLE(0xD),
/**
* Represents yellow
*/
YELLOW(0xE),
/**
* Represents white
*/
WHITE(0xF);
private final int code;
@ -31,6 +79,11 @@ public enum ChatColor {
this.code = code;
}
/**
* Gets the data value associated with this color
*
* @return An integer value of this color code
*/
public int getCode() {
return code;
}
@ -40,6 +93,12 @@ public enum ChatColor {
return String.format("\u00A7%x", code);
}
/**
* Gets the color represented by the specified color code
*
* @param code Code to check
* @return Associative {@link Color} with the given code, or null if it doesn't exist
*/
public static ChatColor getByCode(final int code) {
return colors.get(code);
}

59
paper-api/src/main/java/org/bukkit/DyeColor.java
View file

@ -8,21 +8,69 @@ import java.util.Map;
* All supported color values for dyes and cloth
*/
public enum DyeColor {
/**
* Represents white dye
*/
WHITE((byte) 0x0),
/**
* Represents orange dye
*/
ORANGE((byte) 0x1),
/**
* Represents magenta dye
*/
MAGENTA((byte) 0x2),
/**
* Represents light blue dye
*/
LIGHT_BLUE((byte) 0x3),
/**
* Represents yellow dye
*/
YELLOW((byte) 0x4),
/**
* Represents lime dye
*/
LIME((byte) 0x5),
/**
* Represents pink dye
*/
PINK((byte) 0x6),
/**
* Represents gray dye
*/
GRAY((byte) 0x7),
/**
* Represents silver dye
*/
SILVER((byte) 0x8),
/**
* Represents cyan dye
*/
CYAN((byte) 0x9),
/**
* Represents purple dye
*/
PURPLE((byte) 0xA),
/**
* Represents blue dye
*/
BLUE((byte) 0xB),
/**
* Represents brown dye
*/
BROWN((byte) 0xC),
/**
* Represents green dye
*/
GREEN((byte) 0xD),
/**
* Represents red dye
*/
RED((byte) 0xE),
/**
* Represents black dye
*/
BLACK((byte) 0xF);
private final byte data;
@ -32,10 +80,21 @@ public enum DyeColor {
this.data = data;
}
/**
* Gets the associated data value representing this color
*
* @return A byte containing the data value of this color
*/
public byte getData() {
return data;
}
/**
* Gets the DyeColor with the given data value
*
* @param data Data value to fetch
* @return The {@link DyeColor} representing the given value, or null if it doesn't exist
*/
public static DyeColor getByData(final byte data) {
return colors.get(data);
}

23
paper-api/src/main/java/org/bukkit/Location.java
View file

@ -15,10 +15,28 @@ public class Location implements Cloneable {
private float pitch;
private float yaw;
/**
* Constructs a new Location with the given coordinates
*
* @param world The world in which this location resides
* @param x The x-coordinate of this new location
* @param y The y-coordinate of this new location
* @param z The z-coordinate of this new location
*/
public Location(final World world, final double x, final double y, final double z) {
this(world, x, y, z, 0, 0);
}
/**
* Constructs a new Location with the given coordinates and direction
*
* @param world The world in which this location resides
* @param x The x-coordinate of this new location
* @param y The y-coordinate of this new location
* @param z The z-coordinate of this new location
* @param yaw The absolute rotation on the x-plane, in degrees
* @param pitch The absolute rotation on the y-plane, in degrees
*/
public Location(final World world, final double x, final double y, final double z, final float yaw, final float pitch) {
this.world = world;
this.x = x;
@ -242,6 +260,11 @@ public class Location implements Cloneable {
return "Location{" + "world=" + world + "x=" + x + "y=" + y + "z=" + z + "pitch=" + pitch + "yaw=" + yaw + '}';
}
/**
* Constructs a new {@link Vector} based on this Location
*
* @return New Vector containing the coordinates represented by this Location
*/
public Vector toVector() {
return new Vector(x, y, z);
}

245
paper-api/src/main/java/org/bukkit/World.java
View file

@ -17,54 +17,52 @@ import org.bukkit.entity.Arrow;
import org.bukkit.entity.Boat;
/**
* Represents a world.
*
* Currently there is only one world in the default Minecraft spec, but this
* may change with the addition of a functional Nether world
* Represents a world, which may contain entities, chunks and blocks
*/
public interface World {
/**
* Gets the block at the given location
*
* This block will always represent the latest state
* Gets the {@link Block} at the given coordinates
*
* @param x X-coordinate of the block
* @param y Y-coordinate of the block
* @param z Z-coordinate of the block
* @return Block at the given location
* @return Block at the given coordinates
* @see #getBlockTypeIdAt(int, int, int) Returns the current type ID of the block
*/
public Block getBlockAt(int x, int y, int z);
/**
* Gets the block at the given location
*
* This block will always represent the latest state
* Gets the {@link Block} at the given {@link Location}
*
* @param location Location of the block
* @return Block at the given location
* @see #getBlockTypeIdAt(org.bukkit.Location) Returns the current type ID of the block
*/
public Block getBlockAt(Location location);
/**
* Gets the block type-id at the given location
* Gets the block type ID at the given coordinates
*
* @param x X-coordinate of the block
* @param y Y-coordinate of the block
* @param z Z-coordinate of the block
* @return TypeId of the block at the given location
* @return Type ID of the block at the given coordinates
* @see #getBlockAt(int, int, int) Returns a live Block object at the given location
*/
public int getBlockTypeIdAt(int x, int y, int z);
/**
* Gets the block type-id at the given location
* Gets the block type ID at the given {@link Location}
*
* @param location Location of the block
* @return TypeId of the block at the given location
* @return Type ID of the block at the given location
* @see #getBlockAt(org.bukkit.Location) Returns a live Block object at the given location
*/
public int getBlockTypeIdAt(Location location);
/**
* Gets the highest non-air coordinate at the given (x,z) location
* Gets the highest non-air coordinate at the given coordinates
*
* @param x X-coordinate of the blocks
* @param z Z-coordinate of the blocks
* @return Y-coordinate of the highest non-air block
@ -72,23 +70,24 @@ public interface World {
public int getHighestBlockYAt(int x, int z);
/**
* Gets the highest non-air coordinate at the given location
* Gets the highest non-air coordinate at the given {@link Location}
*
* @param location Location of the blocks
* @return Y-coordinate of the highest non-air block
*/
public int getHighestBlockYAt(Location location);
/**
* Gets the chunk at the given location
* Gets the {@link Chunk} at the given coordinates
*
* @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk
* @return Chunk at the given location
* @return Chunk at the given coordinates
*/
public Chunk getChunkAt(int x, int z);
/**
* Gets the chunk at the given location
* Gets the {@link Chunk} at the given {@link Location}
*
* @param location Location of the chunk
* @return Chunk at the given location
@ -96,35 +95,37 @@ public interface World {
public Chunk getChunkAt(Location location);
/**
* Gets the chunk which contains the given block
* Gets the {@link Chunk} that contains the given {@link Block}
*
* @param block Block to get the parent chunk from
* @return Chunk that contains the given block
* @param block Block to get the containing chunk from
* @return The chunk that contains the given block
*/
public Chunk getChunkAt(Block block);
/**
* Checks if the specified chunk is loaded
* Checks if the specified {@link Chunk} is loaded
*
* @param chunk The chunk to check
* @return true if the chunk is loaded, otherwise false
*/
public boolean isChunkLoaded(Chunk chunk);
/**
* Gets an array of all loaded chunks
* Gets an array of all loaded {@link Chunk}s
*
* @return Chunk array of all loaded chunks
* @return Chunk[] containing all loaded chunks
*/
public Chunk[] getLoadedChunks();
/**
* Loads the specified chunk
* Loads the specified {@link Chunk}
*
* @param chunk The chunk to load
*/
public void loadChunk(Chunk chunk);
/**
* Checks if the chunk at the specified coordinates is loaded
* Checks if the {@link Chunk} at the specified coordinates is loaded
*
* @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk
@ -133,58 +134,74 @@ public interface World {
public boolean isChunkLoaded(int x, int z);
/**
* Loads the chunk at the specified coordinates and generates the chunk when it is non-existing
* 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
*/
public void loadChunk(int x, int z);
/**
* Loads the chunk at the specified coordinates and generates the chunk when it is non-existing if generate is enabled
* Loads the {@link Chunk} at the specified coordinates
*
* @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk
* @param generate Controls whether non-generated chunks are generated
* @return Whether the chunk has loaded
* @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 chunk at the specified coordinates
* 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
*
* @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk
* @return Whether the chunk was actually unloaded
* @return true if the chunk has unloaded successfully, otherwise false
*/
public boolean unloadChunk(int x, int z);
/**
* Safely unloads and optionally saves the chunk at the specified coordinates
* 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 save Controls whether the chunk is saved
* @return Whether the chunk was actually unloaded
* @param save Whether or not to save the chunk
* @return true if the chunk has unloaded successfully, otherwise false
*/
public boolean unloadChunk(int x, int z, boolean save);
/**
* Unloads and optionally saves the chunk at the specified coordinates
* 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 save Controls whether the chunk is saved
* @param safe Controls whether to unload the chunk when players are nearby
* @return Whether the chunk was actually unloaded
* @return true if the chunk has unloaded successfully, otherwise false
*/
public boolean unloadChunk(int x, int z, boolean save, boolean safe);
/**
* Safely queues the chunk at the specified coordinates for unloading
* 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
* @return Whether the chunk was actually queued
* @return true is the queue attempt was successful, otherwise false
*/
public boolean unloadChunkRequest(int x, int z);
/**
* Queues the chunk at the specified coordinates for unloading
* 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 safe Controls whether to queue the chunk when players are nearby
@ -193,171 +210,177 @@ public interface World {
public boolean unloadChunkRequest(int x, int z, boolean safe);
/**
* Drop an item exactly at the specified location.
* Drops an item at the specified {@link Location}
*
* @param loc
* @param item
* @return dropped item entity
* @param location Location to drop the item
* @param item ItemStack to drop
* @return ItemDrop entity created as a result of this method
*/
public ItemDrop dropItem(Location loc, ItemStack item);
public ItemDrop dropItem(Location location, ItemStack item);
/**
* Drop an item as if it was mined (randomly placed).
* Drops an item at the specified {@link Location} with a random offset
*
* @param loc
* @param item
* @return dropped item entity
* @param location Location to drop the item
* @param item ItemStack to drop
* @return ItemDrop entity created as a result of this method
*/
public ItemDrop dropItemNaturally(Location loc, ItemStack item);
public ItemDrop dropItemNaturally(Location location, ItemStack item);
/**
* Spawns an arrow.
* Creates an {@link Arrow} entity at the given {@link Location}
*
* @param loc
* @param velocity velocity vector
* @param speed a reasonable speed is 0.6
* @param spread a reasonable spread is 12
* @return the arrow entity
* @param location Location to spawn the arrow
* @param velocity Velocity to shoot the arrow in
* @param speed Speed of the arrow. A recommend speed is 0.6
* @param spread Spread of the arrow. A recommend spread is 12
* @return Arrow entity spawned as a result of this method
*/
public Arrow spawnArrow(Location loc, Vector velocity, float speed, float spread);
public Arrow spawnArrow(Location location, Vector velocity, float speed, float spread);
/**
* Spawns a tree at a location.
* Creates a tree at the given {@link Location}
*
* @param loc
* @param type
* @return whether the tree was created
* @param location Location to spawn the tree
* @param type Type of the tree to create
* @return true if the tree was created successfully, otherwise false
*/
public boolean generateTree(Location loc, TreeType type);
public boolean generateTree(Location location, TreeType type);
/**
* Spawns a tree at a location.
* Creates a tree at the given {@link Location}
*
* @param loc
* @param type
* @param delegate
* @return whether the tree was created
* @param location Location to spawn the tree
* @param type Type of the tree to create
* @param delegate A class to call for each block changed as a result of this method
* @return true if the tree was created successfully, otherwise false
*/
public boolean generateTree(Location loc, TreeType type, BlockChangeDelegate delegate);
/**
* Spawns a regular passenger minecart.
* Creates a regular passenger minecart at the given {@link Location}
*
* @param loc
* @return
* @param location Location to spawn the minecart
* @return Minecart created as a result of this method
*/
public Minecart spawnMinecart(Location loc);
public Minecart spawnMinecart(Location location);
/**
* Spawns a storage minecart.
* Creates a storage minecart at the given {@link Location}
*
* @param loc
* @return
* @param location Location to spawn the minecart
* @return StorageMinecart created as a result of this method
*/
public StorageMinecart spawnStorageMinecart(Location loc);
/**
* Spawns a powered minecart.
* Creates a powered minecart at the given {@link Location}
*
* @param loc
* @return
* @param location Location to spawn the minecart
* @return PoweredMinecart created as a result of this method
*/
public PoweredMinecart spawnPoweredMinecart(Location loc);
/**
* Spawn a boat.
* Creates a boat at the given {@link Location}
*
* @param loc
* @return
* @param location Location to spawn the boat
* @return Boat created as a result of this method
*/
public Boat spawnBoat(Location loc);
/**
* Spawn a creature at the given location.
* Creates a creature at the given {@link Location}
*
* @param loc The location to spawn at.
* @param creatureType The creature to spawn.
*
* @return The Creature if it was spawned, null otherwise.
* @param loc The location to spawn the creature
* @param type The creature to spawn
* @return Resulting Creature of this method, or null if it was unsuccessful
*/
public Creature spawnCreature(Location loc, CreatureType creatureType);
public Creature spawnCreature(Location loc, CreatureType type);
/**
* Get a list of all entities.
* Get a list of all entities in this World
*
* @return
* @return A List of all Entities currently residing in this world
*/
public List<Entity> getEntities();
/**
* Get a list of all living entities.
* Get a list of all living entities in this World
*
* @return
* @return A List of all LivingEntities currently residing in this world
*/
public List<LivingEntity> getLivingEntities();
/**
* Gets the name of this world. This is not guaranteed to be unique.
* Gets the unique name of this world
*
* @return Name of this world
*/
public String getName();
/**
* Gets a semi-unique identifier for this world. While it is highly unlikely
* that this may be shared with another World, it is not guaranteed to be
* unique.
* Gets a semi-unique identifier for this world.
*
* While it is highly unlikely that this may be shared with another World,
* it is not guaranteed to be unique
*
* @return Id of this world
*/
public long getId();
/**
* Gets the default spawn location.
* Gets the default spawn {@link Location} of this world
*
* @return The spawn location of this world
*/
public Location getSpawnLocation();
/**
* Gets the relative in-game time on this world (in hours*1000)
* Gets the relative in-game time of this world.
*
* @return The current relative time in hours*1000
* @see getFullTime
* The relative time is analogous to hours * 1000
*
* @return The current relative time
* @see #getFullTime() Returns an absolute time of this world
*/
public long getTime();
/**
* Sets the relative in-game time on the server (in hours*1000)<br />
* <br />
* Sets the relative in-game time on the server.
*
* The relative time is analogous to hours * 1000
* <br /><br />
* 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
*
* @param time The new relative time to set the in-game time to (in hours*1000)
* @see setFullTime
* @see #setFullTime(long) Sets the absolute time of this world
*/
public void setTime(long time);
/**
* Gets the full in-game time on this world (in hours*1000)
* Gets the full in-game time on this world
*
* @return The current time in hours*1000
* @see setTime
* @return The current absolute time
* @see #getTime() Returns a relative time of this world
*/
public long getFullTime();
/**
* Sets the in-game time on the server (in hours*1000)<br />
* <br />
* Sets the in-game time on the server
* <br /><br />
* Note that this sets the full time of the world, which may cause adverse
* effects such as breaking redstone clocks and any scheduled events
*
* @param time The new time to set the in-game time to (in hours*1000)
* @see setTime
* @param time The new absolute time to set this world to
* @see #setTime(long) Sets the relative time of this world
*/
public void setFullTime(long time);
/**
* Gets the environment type of this world
* Gets the {@link Environment} type of this world
*
* @return This worlds Environment type
*/