OpenSource/PaperMC
OpenSource/PaperMC
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-01-15 14:13:56 +01:00
Code Issues Projects Releases Packages Wiki Activity

Fix upstream javadocs

Browse source
This commit is contained in:
Zach Brown 2017-06-10 16:59:40 -05:00
parent f7eff332be
commit 0c37d20354
75 changed files with 403 additions and 173 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
paper-api/src/main/java/org/bukkit/BanList.java
View file

@ -38,6 +38,9 @@ public interface BanList<T> {
/**
* Gets a {@link BanEntry} by target.
* <p>
* Bans by name for ban type {@link Type#NAME NAME} are no longer supported and this method will return
* null when trying to request them. The replacement is bans by UUID.
*
* @param target entry parameter to search for
* @return the corresponding entry, or null if none found
@ -59,6 +62,9 @@ public interface BanList<T> {
/**
* Adds a ban to this list. If a previous ban exists, this will
* update the previous entry.
* <p>
* Bans by name for ban type {@link Type#NAME NAME} are no longer supported and this method will return
* null when trying to request them. The replacement is bans by UUID.
*
* @param target the target of the ban
* @param reason reason for the ban, null indicates implementation default
@ -139,6 +145,9 @@ public interface BanList<T> {
/**
* Gets if a {@link BanEntry} exists for the target, indicating an active
* ban status.
* <p>
* Bans by name for ban type {@link Type#NAME NAME} are no longer supported.
* The replacement is bans by UUID.
*
* @param target the target to find
* @return true if a {@link BanEntry} exists for the target, indicating an
@ -161,6 +170,9 @@ public interface BanList<T> {
/**
* Removes the specified target from this list, therefore indicating a
* "not banned" status.
* <p>
* Bans by name for ban type {@link Type#NAME NAME} are no longer supported.
* The replacement is bans by UUID.
*
* @param target the target to remove from this list
*/

4
paper-api/src/main/java/org/bukkit/Bukkit.java
View file

@ -1538,6 +1538,8 @@ public final class Bukkit {
/**
* Gets every player that has ever played on this server.
* <p>
* <b>This method can be expensive as it loads all the player data files from the disk.</b>
*
* @return an array containing all previous players
*/
@ -2059,7 +2061,7 @@ public final class Bukkit {
* server will pause most functions after this time if there are no players
* online.
* <p>
* A value of less than 0 will disable the setting
* A value of less than 1 will disable the setting
*
* @param seconds the pause threshold in seconds
*/

2
paper-api/src/main/java/org/bukkit/ChunkSnapshot.java
View file

@ -136,7 +136,7 @@ public interface ChunkSnapshot {
* Get raw biome temperature at given coordinates
*
* @param x X-coordinate (0-15)
* @param y Y-coordinate (0-15)
* @param y Y-coordinate (world minHeight (inclusive) - world maxHeight (exclusive))
* @param z Z-coordinate (0-15)
* @return temperature at given coordinate
*/

3
paper-api/src/main/java/org/bukkit/HeightMap.java
View file

@ -12,8 +12,7 @@ public enum HeightMap {
*/
MOTION_BLOCKING,
/**
* The highest block that blocks motion or contains a fluid or is in the
* {@link Tag#LEAVES}.
* The highest block that blocks motion or contains a fluid, excluding leaves.
*/
MOTION_BLOCKING_NO_LEAVES,
/**

2
paper-api/src/main/java/org/bukkit/Particle.java
View file

@ -207,7 +207,7 @@ public enum Particle implements Keyed {
}
/**
* Options which can be applied to redstone dust particles - a particle
* Options which can be applied to dust particles - a particle
* color and size.
*/
public static class DustOptions {

8
paper-api/src/main/java/org/bukkit/RegionAccessor.java
View file

@ -158,7 +158,7 @@ public interface RegionAccessor {
* Creates a tree at the given {@link Location}
*
* @param location Location to spawn the tree
* @param random Random to use to generated the tree
* @param random Random to use to generate the tree
* @param type Type of the tree to create
* @return true if the tree was created successfully, otherwise false
*/
@ -170,14 +170,14 @@ public interface RegionAccessor {
* The provided consumer gets called for every block which gets changed
* as a result of the tree generation. When the consumer gets called no
* modifications to the world are done yet. Which means, that calling
* {@link #getBlockState(Location)} in the consumer while return the state
* {@link #getBlockState(Location)} in the consumer will return the state
* of the block before the generation.
* <p>
* Modifications done to the {@link BlockState} in the consumer are respected,
* which means that it is not necessary to call {@link BlockState#update()}
*
* @param location Location to spawn the tree
* @param random Random to use to generated the tree
* @param random Random to use to generate the tree
* @param type Type of the tree to create
* @param stateConsumer The consumer which should get called for every block which gets changed
* @return true if the tree was created successfully, otherwise false
@ -197,7 +197,7 @@ public interface RegionAccessor {
* If it returns {@code false} the block won't get set in the world.
*
* @param location Location to spawn the tree
* @param random Random to use to generated the tree
* @param random Random to use to generate the tree
* @param type Type of the tree to create
* @param statePredicate The predicate which should get used to test if a block should be set or not.
* @return true if the tree was created successfully, otherwise false

9
paper-api/src/main/java/org/bukkit/Server.java
View file

@ -581,13 +581,10 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
* </ul>
* <p>
* <b>Note:</b> If set to 0, {@link SpawnCategory} mobs spawning will be disabled.
* <p>
* Minecraft default: 1.
* <br>
* <b>Note: </b> the {@link SpawnCategory#MISC} are not consider.
*
* @param spawnCategory the category of spawn
* @return the default ticks per {@link SpawnCategory} mobs spawn value
* @throws IllegalArgumentException if the category is {@link SpawnCategory#MISC}
*/
public int getTicksPerSpawns(@NotNull SpawnCategory spawnCategory);
@ -1298,6 +1295,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
/**
* Gets every player that has ever played on this server.
* <p>
* <b>This method can be expensive as it loads all the player data files from the disk.</b>
*
* @return an array containing all previous players
*/
@ -1740,7 +1739,7 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
* Sets the pause when empty threshold seconds. To save resources, the
* pause most functions after this time if there are no players online.
* <p>
* A value of less than 0 will disable the setting
* A value of less than 1 will disable the setting
*
* @param seconds the pause threshold in seconds
*/

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

@ -2766,7 +2766,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
/**
* Find the closest nearby structure of a given {@link StructureType}.
* Finding unexplored structures can, and will, block if the world is
* looking in chunks that gave not generated yet. This can lead to the world
* looking in chunks that have not generated yet. This can lead to the world
* temporarily freezing while locating an unexplored structure.
* <p>
* The {@code radius} is not a rigid square radius. Each structure may alter
@ -2800,7 +2800,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
/**
* Find the closest nearby structure of a given {@link StructureType}.
* Finding unexplored structures can, and will, block if the world is
* looking in chunks that gave not generated yet. This can lead to the world
* looking in chunks that have not generated yet. This can lead to the world
* temporarily freezing while locating an unexplored structure.
* <p>
* The {@code radius} is not a rigid square radius. Each structure may alter
@ -2833,7 +2833,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
/**
* Find the closest nearby structure of a given {@link Structure}. Finding
* unexplored structures can, and will, block if the world is looking in
* chunks that gave not generated yet. This can lead to the world
* chunks that have not generated yet. This can lead to the world
* temporarily freezing while locating an unexplored structure.
* <p>
* The {@code radius} is not a rigid square radius. Each structure may alter

3
paper-api/src/main/java/org/bukkit/attribute/AttributeModifier.java
View file

@ -129,8 +129,7 @@ public class AttributeModifier implements ConfigurationSerializable, Keyed {
}
/**
* Get the {@link EquipmentSlot} this AttributeModifier is active on,
* or null if this modifier is applicable for any slot.
* Get the {@link EquipmentSlotGroup} this AttributeModifier is active on.
*
* @return the slot
*/

21
paper-api/src/main/java/org/bukkit/block/Bed.java
View file

@ -4,7 +4,22 @@ import org.bukkit.material.Colorable;
/**
* Represents a captured state of a bed.
* @deprecated does not provide useful information beyond the material itself
*/
@Deprecated(since = "1.13")
public interface Bed extends TileState, Colorable { }
// Paper start
// @Deprecated(since = "1.13")
public interface Bed extends TileState, Colorable {
@Override
@org.jetbrains.annotations.NotNull org.bukkit.DyeColor getColor();
/**
* <b>Unsupported</b>
*
* @throws UnsupportedOperationException not supported, set the block type
*/
@Override
@org.jetbrains.annotations.Contract("_ -> fail")
@Deprecated(forRemoval = true)
void setColor(@org.bukkit.UndefinedNullability("not supported") org.bukkit.DyeColor color);
// Paper end
}

21
paper-api/src/main/java/org/bukkit/block/Block.java
View file

@ -357,7 +357,7 @@ public interface Block extends Metadatable, Translatable {
* Gets the temperature of this block.
* <p>
* If the raw biome temperature without adjusting for height effects is
* required then please use {@link World#getTemperature(int, int)}.
* required then please use {@link World#getTemperature(int, int, int)}.
*
* @return Temperature of this block
*/
@ -405,7 +405,10 @@ public interface Block extends Metadatable, Translatable {
boolean applyBoneMeal(@NotNull BlockFace face);
/**
* Returns a list of items which would drop by destroying this block
* Returns a list of items which could drop by destroying this block.
* <p>
* The items are not guaranteed to be consistent across multiple calls to this
* method as this just uses the block type's loot table.
*
* @return a list of dropped items for this type of block
*/
@ -413,8 +416,11 @@ public interface Block extends Metadatable, Translatable {
Collection<ItemStack> getDrops();
/**
* Returns a list of items which would drop by destroying this block with
* a specific tool
* Returns a list of items which could drop by destroying this block with
* a specific tool.
* <p>
* The items are not guaranteed to be consistent across multiple calls to this
* method as this just uses the block type's loot table.
*
* @param tool The tool or item in hand used for digging
* @return a list of dropped items for this type of block
@ -423,8 +429,11 @@ public interface Block extends Metadatable, Translatable {
Collection<ItemStack> getDrops(@Nullable ItemStack tool);
/**
* Returns a list of items which would drop by the entity destroying this
* block with a specific tool
* Returns a list of items which could drop by the entity destroying this
* block with a specific tool.
* <p>
* The items are not guaranteed to be consistent across multiple calls to this
* method as this just uses the block type's loot table.
*
* @param tool The tool or item in hand used for digging
* @param entity the entity destroying the block

2
paper-api/src/main/java/org/bukkit/block/data/BlockData.java
View file

@ -224,7 +224,7 @@ public interface BlockData extends Cloneable {
* {@link Material#REDSTONE_WIRE} -> {@link Material#REDSTONE}
* {@link Material#CARROTS} -> {@link Material#CARROT}
* </pre>
* @return placement material
* @return placement material or {@link Material#AIR} if it doesn't have one
*/
@NotNull
Material getPlacementMaterial();

2
paper-api/src/main/java/org/bukkit/block/data/FaceAttachable.java
View file

@ -38,7 +38,7 @@ public interface FaceAttachable extends BlockData {
*/
WALL,
/**
* The switch is mounted to the ceiling and pointing dowanrds.
* The switch is mounted to the ceiling and pointing downwards.
*/
CEILING;
}

2
paper-api/src/main/java/org/bukkit/block/data/type/CommandBlock.java
View file

@ -4,7 +4,7 @@ import org.bukkit.block.data.Directional;
/**
* 'conditional' denotes whether this command block is conditional or not, i.e.
* will only execute if the preceeding command block also executed successfully.
* will only execute if the preceding command block also executed successfully.
*/
public interface CommandBlock extends Directional {

2
paper-api/src/main/java/org/bukkit/block/data/type/Gate.java
View file

@ -5,7 +5,7 @@ import org.bukkit.block.data.Openable;
import org.bukkit.block.data.Powerable;
/**
* 'in_wall" indicates if the fence gate is attached to a wall, and if true the
* 'in_wall' indicates if the fence gate is attached to a wall, and if true the
* texture is lowered by a small amount to blend in better.
*/
public interface Gate extends Directional, Openable, Powerable {

4
paper-api/src/main/java/org/bukkit/block/data/type/Switch.java
View file

@ -21,7 +21,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
* Sets the value of the 'face' property.
*
* @param face the new 'face' value
* @deprecated use {@link #getAttachedFace()}
* @deprecated use {@link #setAttachedFace(AttachedFace)}
*/
@Deprecated(since = "1.15.2")
void setFace(@NotNull Face face);
@ -42,7 +42,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
*/
WALL,
/**
* The switch is mounted to the ceiling and pointing dowanrds.
* The switch is mounted to the ceiling and pointing downwards.
*/
CEILING;
}

3
paper-api/src/main/java/org/bukkit/entity/ArmorStand.java
View file

@ -360,5 +360,8 @@ public interface ArmorStand extends LivingEntity {
* @param move {@code true} if this armour stand can move, {@code false} otherwise
*/
void setCanMove(boolean move);
@Override
org.bukkit.inventory.@NotNull EntityEquipment getEquipment();
// Paper end
}

2
paper-api/src/main/java/org/bukkit/entity/Arrow.java
View file

@ -93,7 +93,7 @@ public interface Arrow extends AbstractArrow {
* Removes a custom potion effect from this arrow.
*
* @param type the potion effect type to remove
* @return true if the an effect was removed as a result of this call
* @return true if the effect was removed as a result of this call
* @throws IllegalArgumentException if this operation would leave the Arrow
* in a state with no Custom Effects and PotionType.UNCRAFTABLE
*/

2
paper-api/src/main/java/org/bukkit/entity/EnderDragon.java
View file

@ -30,7 +30,7 @@ public interface EnderDragon extends ComplexLivingEntity, Boss, Mob, Enemy {
*/
FLY_TO_PORTAL,
/**
* The dragon will land on on the portal. If the dragon is not near
* The dragon will land on the portal. If the dragon is not near
* the portal, it will fly to it before mounting.
*/
LAND_ON_PORTAL,

8
paper-api/src/main/java/org/bukkit/entity/Entity.java
View file

@ -180,9 +180,13 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
public List<org.bukkit.entity.Entity> getNearbyEntities(double x, double y, double z);
/**
* Returns a unique id for this entity
* Returns the network protocol ID for this entity. This is
* not to be used as an identifier for the entity except in
* network-related operations. Use {@link #getUniqueId()} as
* an entity identifier instead.
*
* @return Entity id
* @return the network protocol ID
* @see #getUniqueId()
*/
public int getEntityId();

5
paper-api/src/main/java/org/bukkit/entity/HumanEntity.java
View file

@ -22,6 +22,11 @@ import org.jetbrains.annotations.Nullable;
*/
public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder {
// Paper start
@Override
org.bukkit.inventory.@NotNull EntityEquipment getEquipment();
// Paper end
/**
* Returns the name of this player
*

2
paper-api/src/main/java/org/bukkit/entity/ItemFrame.java
View file

@ -75,7 +75,7 @@ public interface ItemFrame extends Hanging {
public void setRotation(@NotNull Rotation rotation) throws IllegalArgumentException;
/**
* Returns whether the item frame is be visible or not.
* Returns whether the item frame is visible or not.
*
* @return whether the item frame is visible or not
*/

2
paper-api/src/main/java/org/bukkit/entity/LivingEntity.java
View file

@ -502,7 +502,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
/**
* Sets the leash on this entity to be held by the supplied entity.
* <p>
* This method has no effect on EnderDragons, Withers, Players, or Bats.
* This method has no effect on players.
* Non-living entities excluding leashes will not persist as leash
* holders.
*

4
paper-api/src/main/java/org/bukkit/entity/Mob.java
View file

@ -9,6 +9,10 @@ import org.jetbrains.annotations.Nullable;
*/
public interface Mob extends LivingEntity, Lootable {
// Paper start
@Override
org.bukkit.inventory.@org.jetbrains.annotations.NotNull EntityEquipment getEquipment();
// Paper end
/**
* Instructs this Mob to set the specified LivingEntity as its target.
* <p>

2
paper-api/src/main/java/org/bukkit/entity/PigZombie.java
View file

@ -44,8 +44,6 @@ public interface PigZombie extends Zombie {
/**
* <b>Not applicable to this entity</b>
*
* @return UnsuppotedOperationException
*/
@Override
public int getConversionTime();

25
paper-api/src/main/java/org/bukkit/entity/Player.java
View file

@ -492,15 +492,15 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Saves the players current location, health, inventory, motion, and
* other information into the uuid.dat file, in the &lt;main
* world&gt;/playerdata folder.
* other information into the &lt;uuid&gt;.dat file, in the
* &lt;level-name&gt;/playerdata/ folder.
*/
public void saveData();
/**
* Loads the players current location, health, inventory, motion, and
* other information from the uuid.dat file, in the &lt;main
* world&gt;/playerdata folder.
* other information from the &lt;uuid&gt;.dat file, in the
* &lt;level-name&gt;/playerdata/ folder.
* <p>
* Note: This will overwrite the players current inventory, health,
* motion, etc, with the state from the saved dat file.
@ -861,7 +861,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Plays an effect to just this player.
*
* @param <T> the data based based on the type of the effect
* @param <T> the data based on the type of the effect
* @param loc the location to play the effect at
* @param effect the {@link Effect}
* @param data a data bit needed for some effects
@ -1272,7 +1272,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
*
* Use supplied alternative character to the section symbol to represent legacy color codes.
*
* @param alternateChar Alternate symbol such as '&'
* @param alternateChar Alternate symbol such as '&amp;'
* @param message The message to send
* @deprecated use {@link #sendActionBar(net.kyori.adventure.text.Component)}
*/
@ -1745,7 +1745,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Allows this player to see a player that was previously hidden. If
* another another plugin had hidden the player too, then the player will
* another plugin had hidden the player too, then the player will
* remain hidden until the other plugin calls this method too.
*
* @param plugin Plugin that wants to show the player
@ -1772,7 +1772,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Allows this player to see an entity that was previously hidden. If
* another another plugin had hidden the entity too, then the entity will
* another plugin had hidden the entity too, then the entity will
* remain hidden until the other plugin calls this method too.
*
* @param plugin Plugin that wants to show the entity
@ -1855,9 +1855,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
* case this method will have no affect on them. Use the
* {@link PlayerResourcePackStatusEvent} to figure out whether or not
* the player loaded the pack!
* <li>There is no concept of resetting texture packs back to default
* within Minecraft, so players will have to relog to do so or you
* have to send an empty pack.
* <li>The request is send with "null" as the hash. This might result
* in newer versions not loading the pack correctly.
* </ul>
@ -1891,9 +1888,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
* case this method will have no affect on them. Use the
* {@link PlayerResourcePackStatusEvent} to figure out whether or not
* the player loaded the pack!
* <li>There is no concept of resetting resource packs back to default
* within Minecraft, so players will have to relog to do so or you
* have to send an empty pack.
* <li>The request is send with empty string as the hash. This might result
* in newer versions not loading the pack correctly.
* </ul>
@ -1930,9 +1924,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
* case this method will have no affect on them. Use the
* {@link PlayerResourcePackStatusEvent} to figure out whether or not
* the player loaded the pack!
* <li>There is no concept of resetting resource packs back to default
* within Minecraft, so players will have to relog to do so or you
* have to send an empty pack.
* <li>The request is sent with empty string as the hash when the hash is
* not provided. This might result in newer versions not loading the
* pack correctly.

10
paper-api/src/main/java/org/bukkit/entity/Slime.java
View file

@ -11,6 +11,16 @@ public interface Slime extends Mob, Enemy {
public int getSize();
/**
* Setting the size of the slime (regardless of previous size)
* will set the following attributes:
* <ul>
* <li>{@link org.bukkit.attribute.Attribute#MAX_HEALTH}</li>
* <li>{@link org.bukkit.attribute.Attribute#MOVEMENT_SPEED}</li>
* <li>{@link org.bukkit.attribute.Attribute#ATTACK_DAMAGE}</li>
* </ul>
* to their per-size defaults and heal the
* slime to its max health (assuming it's alive).
*
* @param sz The new size of the slime.
*/
public void setSize(int sz);

5
paper-api/src/main/java/org/bukkit/entity/Sniffer.java
View file

@ -12,8 +12,6 @@ public interface Sniffer extends Animals {
/**
* Gets the locations explored by the sniffer.
* <br>
* <b>Note:</b> the returned locations use sniffer's current world.
*
* @return a collection of locations
*/
@ -22,9 +20,6 @@ public interface Sniffer extends Animals {
/**
* Remove a location of the explored locations.
* <br>
* <b>Note:</b> the location must be in the sniffer's current world for this
* method to have any effect.
*
* @param location the location to remove
* @see #getExploredLocations()

2
paper-api/src/main/java/org/bukkit/entity/Villager.java
View file

@ -224,7 +224,7 @@ public interface Villager extends AbstractVillager {
*/
Profession NITWIT = getProfession("nitwit");
/**
* Sheperd profession. Wears a brown robe. Shepherds primarily trade for
* Shepherd profession. Wears a brown robe. Shepherds primarily trade for
* wool items, and shears.
*/
Profession SHEPHERD = getProfession("shepherd");

10
paper-api/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
View file

@ -10,15 +10,19 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
* Called if a block broken by a player drops an item.
* Called after a block is broken by a player and potential drops are computed, even if said blocks loot table
* does not define any drops at the point the event is constructed.
*
* If the block break is cancelled, this event won't be called.
*
* If isDropItems in BlockBreakEvent is set to false, this event won't be
* If isDropItems in {@link org.bukkit.event.block.BlockBreakEvent} is set to false, this event won't be
* called.
*
* If a block is broken and isDropItems is set to true, this event will be called even if the block does
* not drop any items, for example glass broken by hand. In this case, #getItems() will be empty.
*
* This event will also be called if the player breaks a multi block structure,
* for example a torch on top of a stone. Both items will have an event call.
* for example a torch on top of a stone. Both items will be included in the #getItems() list.
*
* The Block is already broken as this event is called, so #getBlock() will be
* AIR in most cases. Use #getBlockState() for more Information about the broken

3
paper-api/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
View file

@ -14,6 +14,9 @@ import org.jetbrains.annotations.NotNull;
* Note that due to the nature of explosions, {@link #getBlock()} will always be
* an air block. {@link #getExplodedBlockState()} should be used to get
* information about the block state that exploded.
* <p>
* The event isn't called if the {@link org.bukkit.GameRule#MOB_GRIEFING}
* is disabled as no block interaction will occur.
*/
public class BlockExplodeEvent extends BlockEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();

2
paper-api/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
View file

@ -34,7 +34,7 @@ public class BlockPistonRetractEvent extends BlockPistonEvent {
/**
* Get an immutable list of the blocks which will be moved by the
* extending.
* retracting.
*
* @return Immutable list of the moved blocks.
*/

2
paper-api/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
View file

@ -114,7 +114,7 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
/**
* Gets the value whether the player would be allowed to build here.
* Defaults to spawn if the server was going to stop them (such as, the
* Defaults to false if the server was going to stop them (such as, the
* player is in Spawn). Note that this is an entirely different check
* than BLOCK_CANBUILD, as this refers to a player, not universe-physics
* rule like cactus on dirt.

2
paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
View file

@ -81,7 +81,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
/**
* Get a list of available {@link EnchantmentOffer} for the player. You can
* modify the values to change the available offers for the player. An offer
* may be null, if there isn't a enchantment offer at a specific slot. There
* may be null, if there isn't an enchantment offer at a specific slot. There
* are 3 slots in the enchantment table available to modify.
*
* @return list of available enchantment offers

2
paper-api/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
View file

@ -8,7 +8,7 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
* Called when a lingering potion applies it's effects. Happens
* Called when a lingering potion applies its effects. Happens
* once every 5 ticks
*/
public class AreaEffectCloudApplyEvent extends EntityEvent implements Cancellable {

5
paper-api/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
View file

@ -158,11 +158,12 @@ public class CreatureSpawnEvent extends EntitySpawnEvent {
*/
DROWNED,
/**
* When an cow is spawned by shearing a mushroom cow
* When a cow is spawned by shearing a mushroom cow
*/
SHEARED,
/**
* When eg an effect cloud is spawned as a result of a creeper exploding
* When an entity is spawned as a result of an explosion. Like an area effect cloud from
* a creeper or a dragon fireball.
*/
EXPLOSION,
/**

7
paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
View file

@ -12,6 +12,10 @@ import org.jetbrains.annotations.Nullable;
/**
* Called when an entity is damaged by a block
* <p>
* For explosions, the Block returned by {@link #getDamager()} has
* already been cleared. See {@link #getDamagerBlockState()} for a snapshot
* of the block if it has already been changed.
*/
public class EntityDamageByBlockEvent extends EntityDamageEvent {
private final Block damager;
@ -51,6 +55,9 @@ public class EntityDamageByBlockEvent extends EntityDamageEvent {
/**
* Returns the captured BlockState of the block that damaged the player.
* <p>
* This block state is not placed so {@link org.bukkit.block.BlockState#isPlaced}
* will be false.
*
* @return the block state
*/

4
paper-api/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
View file

@ -10,7 +10,9 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
* Called when an entity explodes
* Called when an entity explodes interacting with blocks. The
* event isn't called if the {@link org.bukkit.GameRule#MOB_GRIEFING}
* is disabled as no block interaction will occur.
*/
public class EntityExplodeEvent extends EntityEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();

2
paper-api/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
View file

@ -7,7 +7,7 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
* Thrown when a entity picks an item up from the ground
* Thrown when an entity picks an item up from the ground
*/
public class EntityPickupItemEvent extends EntityEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();

2
paper-api/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
View file

@ -11,7 +11,7 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Triggered when a entity is created in the world by a player "placing" an item
* Triggered when an entity is created in the world by a player "placing" an item
* on a block.
* <br>
* Note that this event is currently only fired for four specific placements:

4
paper-api/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
View file

@ -133,7 +133,7 @@ public class EntityPotionEffectEvent extends EntityEvent implements Cancellable
public enum Action {
/**
* When the potion effect is added because the entity didn't have it's
* When the potion effect is added because the entity didn't have its
* type.
*/
ADDED,
@ -237,7 +237,7 @@ public class EntityPotionEffectEvent extends EntityEvent implements Cancellable
*/
SPIDER_SPAWN,
/**
* When the entity gets effects from a totem item saving it's life.
* When the entity gets effects from a totem item saving its life.
*/
TOTEM,
/**

2
paper-api/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
View file

@ -105,7 +105,7 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
*/
SATIATED,
/**
* When a player regains health from eating consumables
* When an animal regains health from eating consumables
*/
EATING,
/**

2
paper-api/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
View file

@ -156,7 +156,7 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable {
FOLLOW_LEADER,
/**
* When another entity tempts this entity by having a desired item such
* as wheat in it's hand.
* as wheat in its hand.
*/
TEMPT,
/**

3
paper-api/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
View file

@ -10,8 +10,7 @@ import org.jetbrains.annotations.NotNull;
/**
* Stores all data related to the bartering interaction with a piglin.
*
* This event can be triggered by a piglin picking up an item that's on its
* bartering list.
* Called when a piglin completes a barter.
*/
public class PiglinBarterEvent extends EntityEvent implements Cancellable {

4
paper-api/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
View file

@ -8,7 +8,9 @@ import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
/**
* Called when an ItemStack is successfully burned as fuel in a furnace.
* Called when an ItemStack is successfully burned as fuel in a furnace-like block such as a
* {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, or
* {@link org.bukkit.block.BlastFurnace}.
*/
public class FurnaceBurnEvent extends BlockEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();

4
paper-api/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
View file

@ -9,7 +9,9 @@ import org.bukkit.material.MaterialData;
import org.jetbrains.annotations.NotNull;
/**
* This event is called when a player takes items out of the furnace
* This event is called when a player takes items out of a furnace-like block such as a
* {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, or
* {@link org.bukkit.block.BlastFurnace}.
*/
public class FurnaceExtractEvent extends BlockExpEvent {
private final Player player;

4
paper-api/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
View file

@ -6,7 +6,9 @@ import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
/**
* Called when an ItemStack is successfully smelted in a furnace.
* Called when an ItemStack is successfully smelted in a furnace-like block
* such as a {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker},
* or {@link org.bukkit.block.BlastFurnace}.
*/
public class FurnaceSmeltEvent extends BlockCookEvent {

5
paper-api/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
View file

@ -8,7 +8,10 @@ import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
/**
* Called when a Furnace starts smelting.
* Called when any of the furnace-like blocks start smelting.
* <p>
* Furnace-like blocks are {@link org.bukkit.block.Furnace},
* {@link org.bukkit.block.Smoker}, and {@link org.bukkit.block.BlastFurnace}.
*/
public class FurnaceStartSmeltEvent extends InventoryBlockStartEvent {
private static final HandlerList handlers = new HandlerList();

12
paper-api/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
View file

@ -16,12 +16,16 @@ import org.jetbrains.annotations.Nullable;
/**
* This event is called when a player clicks in an inventory.
* <p>
* In case of a drag action within an inventory, InventoryClickEvent is never called.
* Instead, {@link InventoryDragEvent} is called at the end of the drag.
* <p>
* Because InventoryClickEvent occurs within a modification of the Inventory,
* not all Inventory related methods are safe to use.
* <p>
* The following should never be invoked by an EventHandler for
* InventoryClickEvent using the HumanEntity or InventoryView associated with
* this event:
* Methods that change the view a player is looking at should never be invoked
* by an EventHandler for InventoryClickEvent using the HumanEntity or
* InventoryView associated with this event.
* Examples of these include:
* <ul>
* <li>{@link HumanEntity#closeInventory()}
* <li>{@link HumanEntity#openInventory(Inventory)}
@ -92,7 +96,7 @@ public class InventoryClickEvent extends InventoryInteractEvent {
/**
* Gets the ItemStack currently in the clicked slot.
*
* @return the item in the clicked
* @return the item in the clicked slot
*/
@Nullable
public ItemStack getCurrentItem() {

21
paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
View file

@ -7,7 +7,26 @@ import org.bukkit.inventory.InventoryView;
import org.jetbrains.annotations.NotNull;
/**
* Represents a player related inventory event
* This event is called when a player closes an inventory.
* <p>
* Because InventoryCloseEvent occurs within a modification of the Inventory,
* not all Inventory related methods are safe to use.
* <p>
* Methods that change the view a player is looking at should never be invoked
* by an EventHandler for InventoryCloseEvent using the HumanEntity or
* InventoryView associated with this event.
* Examples of these include:
* <ul>
* <li>{@link HumanEntity#closeInventory()}
* <li>{@link HumanEntity#openInventory(org.bukkit.inventory.Inventory)}
* <li>{@link HumanEntity#openWorkbench(org.bukkit.Location, boolean)}
* <li>{@link HumanEntity#openEnchanting(org.bukkit.Location, boolean)}
* <li>{@link InventoryView#close()}
* </ul>
* To invoke one of these methods, schedule a task using
* {@link org.bukkit.scheduler.BukkitScheduler#runTask(org.bukkit.plugin.Plugin, Runnable)}, which will run the task
* on the next tick. Also be aware that this is not an exhaustive list, and
* other methods could potentially create issues as well.
*/
public class InventoryCloseEvent extends InventoryEvent {
private static final HandlerList handlers = new HandlerList();

2
paper-api/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
View file

@ -7,7 +7,7 @@ import org.bukkit.inventory.InventoryView;
import org.jetbrains.annotations.NotNull;
/**
* Represents a player related inventory event
* Called when a player opens an inventory
*/
public class InventoryOpenEvent extends InventoryEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();

14
paper-api/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
View file

@ -24,6 +24,20 @@ public class PrepareAnvilEvent extends PrepareInventoryResultEvent {
return (AnvilInventory) super.getInventory();
}
/**
* {@inheritDoc}
*
* <p>
* Note: by default custom recipes in anvil are disabled
* you should define a repair cost on the anvil inventory
* greater or equals to zero in order to allow that.
*
* @param result result item
*/
public void setResult(@Nullable ItemStack result) {
super.setResult(result);
}
@NotNull
@Override
public AnvilView getView() {

7
paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
View file

@ -106,7 +106,9 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell
*
* @param player New player which this event will execute as
* @throws IllegalArgumentException if the player provided is null
* @deprecated Only works for sign commands; use {@link Player#performCommand(String)}, including those cases
*/
@Deprecated(forRemoval = true)
public void setPlayer(@NotNull final Player player) throws IllegalArgumentException {
Preconditions.checkArgument(player != null, "Player cannot be null");
this.player = player;
@ -123,11 +125,10 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell
* unmodifiable set.
*
* @return All Players who will see this chat message
* @deprecated This method is provided for backward compatibility with no
* guarantee to the effect of viewing or modifying the set.
* @deprecated This is simply the online players. Modifications have no effect
*/
@NotNull
@Deprecated(since = "1.3.1")
@Deprecated(since = "1.3.1", forRemoval = true)
public Set<Player> getRecipients() {
return recipients;
}

5
paper-api/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
View file

@ -6,8 +6,9 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
* Called when a player takes action on a resource pack request sent via
* {@link Player#setResourcePack(java.lang.String)}.
* Called when a player takes action on a resource pack request.
* @see Player#setResourcePack(String, String)
* @see Player#setResourcePack(String, String, boolean)
*/
public class PlayerResourcePackStatusEvent extends PlayerEvent {

2
paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java
View file

@ -627,7 +627,7 @@ public abstract class ChunkGenerator {
* Get the biome at x, y, z within chunk being generated
*
* @param x the x location in the chunk from 0-15 inclusive
* @param y the y location in the chunk from minimum (inclusive) -
* @param y the y location in the chunk from minHeight (inclusive) -
* maxHeight (exclusive)
* @param z the z location in the chunk from 0-15 inclusive
* @return Biome value

169
paper-api/src/main/java/org/bukkit/inventory/EntityEquipment.java
View file

@ -37,9 +37,23 @@ public interface EntityEquipment {
public ItemStack getItem(@NotNull EquipmentSlot slot);
/**
* Gets a copy of the item the entity is currently holding
* Gets the item the entity is currently holding
* in their main hand.
*
* <p>
* This returns a copy if this equipment instance is from a non-player,
* or it's an empty stack (has AIR as its type).
* For non-empty stacks from players, this returns a live mirror. You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getItemInMainHand(); // will return a mirror
* } else {
* equipment.getItemInMainHand(); // will return a copy
* }
* }</pre>
*
* @return the currently held item
*/
@NotNull
@ -61,9 +75,23 @@ public interface EntityEquipment {
void setItemInMainHand(@Nullable ItemStack item, boolean silent);
/**
* Gets a copy of the item the entity is currently holding
* Gets the item the entity is currently holding
* in their off hand.
*
* <p>
* This returns a copy if this equipment instance is from a non-player,
* or it's an empty stack (has AIR as its type).
* For non-empty stacks from players, this returns a live mirror. You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getItemInOffHand(); // will return a mirror
* } else {
* equipment.getItemInOffHand(); // will return a copy
* }
* }</pre>
*
* @return the currently held item
*/
@NotNull
@ -85,7 +113,21 @@ public interface EntityEquipment {
void setItemInOffHand(@Nullable ItemStack item, boolean silent);
/**
* Gets a copy of the item the entity is currently holding
* Gets the item the entity is currently holding
*
* <p>
* This returns a copy if this equipment instance is from a non-player,
* or it's an empty stack (has AIR as its type).
* For non-empty stacks from players, this returns a live mirror. You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getItemInHand(); // will return a mirror
* } else {
* equipment.getItemInHand(); // will return a copy
* }
* }</pre>
*
* @return the currently held item
* @see #getItemInMainHand()
@ -110,11 +152,24 @@ public interface EntityEquipment {
void setItemInHand(@Nullable ItemStack stack);
/**
* Gets a copy of the helmet currently being worn by the entity
* Gets the helmet currently being worn by the entity
*
* <p>
* This returns a copy if this equipment instance is from a non-player.
* For stacks from players, this returns a live mirror (or null). You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getHelmet(); // will return a mirror
* } else {
* equipment.getHelmet(); // will return a copy
* }
* }</pre>
*
* @return The helmet being worn
*/
@Nullable
@org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getHelmet();
/**
@ -133,11 +188,24 @@ public interface EntityEquipment {
void setHelmet(@Nullable ItemStack helmet, boolean silent);
/**
* Gets a copy of the chest plate currently being worn by the entity
* Gets the chest plate currently being worn by the entity
*
* <p>
* This returns a copy if this equipment instance is from a non-player.
* For stacks from players, this returns a live mirror (or null). You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getChestplate(); // will return a mirror
* } else {
* equipment.getChestplate(); // will return a copy
* }
* }</pre>
*
* @return The chest plate being worn
*/
@Nullable
@org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getChestplate();
/**
@ -156,11 +224,24 @@ public interface EntityEquipment {
void setChestplate(@Nullable ItemStack chestplate, boolean silent);
/**
* Gets a copy of the leggings currently being worn by the entity
* Gets the leggings currently being worn by the entity
*
* <p>
* This returns a copy if this equipment instance is from a non-player.
* For stacks from players, this returns a live mirror (or null). You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getLeggings(); // will return a mirror
* } else {
* equipment.getLeggings(); // will return a copy
* }
* }</pre>
*
* @return The leggings being worn
*/
@Nullable
@org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getLeggings();
/**
@ -179,11 +260,24 @@ public interface EntityEquipment {
void setLeggings(@Nullable ItemStack leggings, boolean silent);
/**
* Gets a copy of the boots currently being worn by the entity
* Gets the boots currently being worn by the entity
*
* <p>
* This returns a copy if this equipment instance is from a non-player.
* For stacks from players, this returns a live mirror (or null). You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getBoots(); // will return a mirror
* } else {
* equipment.getBoots(); // will return a copy
* }
* }</pre>
*
* @return The boots being worn
*/
@Nullable
@org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getBoots();
/**
@ -204,12 +298,25 @@ public interface EntityEquipment {
/**
* Gets all ItemStacks from the armor slots.
*
* <p>
* This returns a copy if this equipment instance is from a non-player,
* or it's an empty stack (has AIR as its type).
* For non-empty stacks from players, this returns a live mirror. You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getArmorContents(); // will return an array of mirror
* } else {
* equipment.getArmorContents(); // will return an array of copies
* }
* }</pre>
*
* @return all the ItemStacks from the armor slots. Individual items can be
* null and are returned in a fixed order starting from the boots and going
* up to the helmet
*/
@NotNull
ItemStack[] getArmorContents();
@org.bukkit.UndefinedNullability("not null elements for entities, nullable elements for players") ItemStack @NotNull [] getArmorContents(); // Paper
/**
* Sets the entities armor to the provided array of ItemStacks
@ -249,7 +356,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop killed by anything
* </ul>
*
* @return chance of the currently held item being dropped (1 for non-{@link Mob})
@ -262,7 +370,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance the chance of the main hand item being dropped
@ -276,7 +385,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return chance of the off hand item being dropped (1 for non-{@link Mob})
@ -289,7 +399,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance the chance of off hand item being dropped
@ -302,7 +413,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the helmet being dropped (1 for non-{@link Mob})
@ -314,7 +426,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the helmet being dropped
@ -328,7 +441,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the chest plate being dropped (1 for non-{@link Mob})
@ -341,7 +455,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the chest plate being dropped
@ -355,7 +470,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the leggings being dropped (1 for non-{@link Mob})
@ -368,7 +484,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance chance of the leggings being dropped
@ -381,7 +498,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the boots being dropped (1 for non-{@link Mob})
@ -393,7 +511,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the boots being dropped

2
paper-api/src/main/java/org/bukkit/inventory/ItemFlag.java
View file

@ -35,7 +35,7 @@ public enum ItemFlag {
*/
HIDE_DYE,
/**
* Setting to show/hide armor trim from leather armor.
* Setting to show/hide armor trim from armor.
*/
HIDE_ARMOR_TRIM;
}

6
paper-api/src/main/java/org/bukkit/inventory/PlayerInventory.java
View file

@ -160,7 +160,7 @@ public interface PlayerInventory extends Inventory {
public void setBoots(@Nullable ItemStack boots);
/**
* Gets a copy of the item the player is currently holding
* Gets the item the player is currently holding
* in their main hand.
*
* @return the currently held item
@ -176,7 +176,7 @@ public interface PlayerInventory extends Inventory {
void setItemInMainHand(@Nullable ItemStack item);
/**
* Gets a copy of the item the player is currently holding
* Gets the item the player is currently holding
* in their off hand.
*
* @return the currently held item
@ -192,7 +192,7 @@ public interface PlayerInventory extends Inventory {
void setItemInOffHand(@Nullable ItemStack item);
/**
* Gets a copy of the item the player is currently holding
* Gets the item the player is currently holding
*
* @return the currently held item
* @see #getItemInMainHand()

4
paper-api/src/main/java/org/bukkit/inventory/ShapedRecipe.java
View file

@ -24,8 +24,6 @@ public class ShapedRecipe extends CraftingRecipe {
* @param result The item you want the recipe to create.
* @see ShapedRecipe#shape(String...)
* @see ShapedRecipe#setIngredient(char, Material)
* @see ShapedRecipe#setIngredient(char, Material, int)
* @see ShapedRecipe#setIngredient(char, MaterialData)
* @see ShapedRecipe#setIngredient(char, RecipeChoice)
* @deprecated Recipes must have keys. Use {@link #ShapedRecipe(NamespacedKey, ItemStack)}
* instead.
@ -45,8 +43,6 @@ public class ShapedRecipe extends CraftingRecipe {
* @exception IllegalArgumentException if the {@code result} is an empty item (AIR)
* @see ShapedRecipe#shape(String...)
* @see ShapedRecipe#setIngredient(char, Material)
* @see ShapedRecipe#setIngredient(char, Material, int)
* @see ShapedRecipe#setIngredient(char, MaterialData)
* @see ShapedRecipe#setIngredient(char, RecipeChoice)
*/
public ShapedRecipe(@NotNull NamespacedKey key, @NotNull ItemStack result) {

7
paper-api/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
View file

@ -31,11 +31,8 @@ public class ShapelessRecipe extends CraftingRecipe {
* @param result The item you want the recipe to create.
* @exception IllegalArgumentException if the {@code result} is an empty item (AIR)
* @see ShapelessRecipe#addIngredient(Material)
* @see ShapelessRecipe#addIngredient(MaterialData)
* @see ShapelessRecipe#addIngredient(Material,int)
* @see ShapelessRecipe#addIngredient(int,Material)
* @see ShapelessRecipe#addIngredient(int,MaterialData)
* @see ShapelessRecipe#addIngredient(int,Material,int)
* @see ShapelessRecipe#addIngredient(RecipeChoice)
*/
public ShapelessRecipe(@NotNull NamespacedKey key, @NotNull ItemStack result) {
super(key, checkResult(result));
@ -175,7 +172,7 @@ public class ShapelessRecipe extends CraftingRecipe {
/**
* Removes multiple instances of an ingredient from the list. If there are
* less instances then specified, all will be removed. Only removes exact
* fewer instances than specified, all will be removed. Only removes exact
* matches, with a data value of 0.
*
* @param count The number of copies to remove.

6
paper-api/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
View file

@ -28,7 +28,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
* Create a cooking recipe to craft the specified ItemStack.
* Create a Stonecutting recipe to craft the specified ItemStack.
*
* @param key The unique recipe key
* @param result The item you want the recipe to create.
@ -42,7 +42,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
* Sets the input of this cooking recipe.
* Sets the input of this Stonecutting recipe.
*
* @param input The input material.
* @return The changed recipe, so you can chain calls.
@ -64,7 +64,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
* Sets the input of this cooking recipe.
* Sets the input of this Stonecutting recipe.
*
* @param input The input choice.
* @return The changed recipe, so you can chain calls.

5
paper-api/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
View file

@ -32,6 +32,11 @@ public interface BlockStateMeta extends ItemMeta {
* @param blockState the block state to attach to the block.
* @throws IllegalArgumentException if the blockState is null
* or invalid for this item.
*
* @apiNote As of 1.20.5 the block state carries a copy of the item's data deviations.
* As such, setting the block state via this method will reset secondary deviations of the item meta.
* This can manifest in the addition to an existing lore failing or a change of a previously added display name.
* It is hence recommended to first mutate the block state, set it back, and then mutate the item meta.
*/
void setBlockState(@NotNull BlockState blockState);
}

6
paper-api/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
View file

@ -28,8 +28,7 @@ public interface CrossbowMeta extends ItemMeta {
* Removes all projectiles when given null.
*
* @param projectiles the projectiles to set
* @throws IllegalArgumentException if one of the projectiles is not an
* arrow or firework rocket
* @throws IllegalArgumentException if one of the projectiles is empty
*/
void setChargedProjectiles(@Nullable List<ItemStack> projectiles);
@ -37,8 +36,7 @@ public interface CrossbowMeta extends ItemMeta {
* Adds a charged projectile to this item.
*
* @param item projectile
* @throws IllegalArgumentException if the projectile is not an arrow or
* firework rocket
* @throws IllegalArgumentException if the projectile is empty
*/
void addChargedProjectile(@NotNull ItemStack item);
}

13
paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
View file

@ -328,7 +328,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
/**
* Gets the enchantable component. Higher values allow higher enchantments.
*
* @return max_stack_size
* @return the enchantable value
*/
int getEnchantable();
@ -661,11 +661,6 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
/**
* Gets the item which this item will convert to when used.
* <p>
* The returned component is a snapshot of its current state and does not
* reflect a live view of what is on an item. After changing any value on
* this component, it must be set with {@link #setUseRemainder(ItemStack)}
* to apply the changes.
*
* @return remainder
*/
@ -802,7 +797,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
* The returned component is a snapshot of its current state and does not
* reflect a live view of what is on an item. After changing any value on
* this component, it must be set with
* {@link #setJukeboxPlayable(org.bukkit.inventory.meta.components.JukeboxComponent)}
* {@link #setJukeboxPlayable(org.bukkit.inventory.meta.components.JukeboxPlayableComponent)}
* to apply the changes.
*
* @return component
@ -811,7 +806,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
JukeboxPlayableComponent getJukeboxPlayable();
/**
* Sets the item tool.
* Sets the jukebox playable component.
*
* @param jukeboxPlayable new component
*/
@ -838,7 +833,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
/**
* Return an immutable copy of all {@link Attribute}s and their
* {@link AttributeModifier}s for a given {@link EquipmentSlot}.<br>
* Any {@link AttributeModifier} that does have have a given
* Any {@link AttributeModifier} that does have a given
* {@link EquipmentSlot} will be returned. This is because
* AttributeModifiers without a slot are active in any slot.<br>
* If there are no attributes set for the given slot, an empty map

11
paper-api/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
View file

@ -8,8 +8,9 @@ import org.jetbrains.annotations.Nullable;
/**
* Represents leather armor ({@link Material#LEATHER_BOOTS}, {@link
* Material#LEATHER_CHESTPLATE}, {@link Material#LEATHER_HELMET}, or {@link
* Material#LEATHER_LEGGINGS}) that can be colored.
* Material#LEATHER_LEGGINGS}, {@link Material#LEATHER_CHESTPLATE}, {@link
* Material#LEATHER_HELMET}, {@link Material#LEATHER_HORSE_ARMOR} or {@link
* Material#WOLF_ARMOR}) that can be colored.
*/
public interface LeatherArmorMeta extends ItemMeta {
@ -18,6 +19,9 @@ public interface LeatherArmorMeta extends ItemMeta {
* be {@link ItemFactory#getDefaultLeatherColor()}.
*
* @return the color of the armor, never null
* @apiNote The method yielding {@link ItemFactory#getDefaultLeatherColor()} is incorrect
* for {@link Material#WOLF_ARMOR} as its default color differs. Generally, it is recommended to check
* {@link #isDyed()} to determine if this leather armor is dyed than to compare this color to the default.
*/
@NotNull
Color getColor();
@ -25,8 +29,7 @@ public interface LeatherArmorMeta extends ItemMeta {
/**
* Sets the color of the armor.
*
* @param color the color to set. Setting it to null is equivalent to
* setting it to {@link ItemFactory#getDefaultLeatherColor()}.
* @param color the color to set.
*/
void setColor(@Nullable Color color);

2
paper-api/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
View file

@ -3,7 +3,7 @@ package org.bukkit.inventory.meta;
import org.jetbrains.annotations.NotNull;
/**
* Represents a map that can be scalable.
* Represents an ominous bottle with an amplifier of the bad omen effect.
*/
public interface OminousBottleMeta extends ItemMeta {

7
paper-api/src/main/java/org/bukkit/inventory/meta/components/UseCooldownComponent.java
View file

@ -6,8 +6,7 @@ import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.Nullable;
/**
* Represents a component which determines the cooldown applied to use of this
* item.
* Represents a component which determines the cooldown applied when using this item before it is available for use again.
*/
@ApiStatus.Experimental
public interface UseCooldownComponent extends ConfigurationSerializable {
@ -39,7 +38,7 @@ public interface UseCooldownComponent extends ConfigurationSerializable {
/**
* Sets the custom cooldown group to be used for similar items.
*
* @param song the cooldown group
* @param group the cooldown group
*/
void setCooldownGroup(@Nullable NamespacedKey song);
void setCooldownGroup(@Nullable NamespacedKey group);
}

6
paper-api/src/main/java/org/bukkit/plugin/Plugin.java
View file

@ -18,7 +18,7 @@ import org.jetbrains.annotations.Nullable;
*/
public interface Plugin extends TabExecutor {
/**
* Returns the folder that the plugin data's files are located in. The
* Returns the folder that the plugin data files are located in. The
* folder may not yet exist.
*
* @return The folder
@ -27,9 +27,9 @@ public interface Plugin extends TabExecutor {
public File getDataFolder();
/**
* Returns the plugin.yaml file containing the details for this plugin
* Returns the plugin.yml file containing the details for this plugin
*
* @return Contents of the plugin.yaml file
* @return Contents of the plugin.yml file
* @deprecated May be inaccurate due to different plugin implementations.
* @see Plugin#getPluginMeta()
*/

6
paper-api/src/main/java/org/bukkit/plugin/java/JavaPlugin.java
View file

@ -69,7 +69,7 @@ public abstract class JavaPlugin extends PluginBase {
}
/**
* Returns the folder that the plugin data's files are located in. The
* Returns the folder that the plugin data files are located in. The
* folder may not yet exist.
*
* @return The folder.
@ -127,9 +127,9 @@ public abstract class JavaPlugin extends PluginBase {
}
/**
* Returns the plugin.yaml file containing the details for this plugin
* Returns the plugin.yml file containing the details for this plugin
*
* @return Contents of the plugin.yaml file
* @return Contents of the plugin.yml file
* @deprecated No longer applicable to all types of plugins
*/
@NotNull

3
paper-api/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
View file

@ -31,7 +31,8 @@ public interface PluginMessageRecipient {
/**
* Gets a set containing all the Plugin Channels that this client is
* listening on.
* listening on. Does not contain the BungeeCord channel due to its
* special status.
*
* @return Set containing all the channels that this client may accept.
*/

8
paper-api/src/main/java/org/bukkit/projectiles/ProjectileSource.java
View file

@ -12,6 +12,10 @@ public interface ProjectileSource {
/**
* Launches a {@link Projectile} from the ProjectileSource.
* <p>
* The family of launchProjectile methods only promise the ability to launch projectile types
* that the {@link ProjectileSource} is capable of firing in vanilla.
* Any other types of projectiles *may* be implemented but are not part of the method contract.
*
* @param <T> a projectile subclass
* @param projectile class of the projectile to launch
@ -23,6 +27,10 @@ public interface ProjectileSource {
/**
* Launches a {@link Projectile} from the ProjectileSource with an
* initial velocity.
* <p>
* The family of launchProjectile methods only promise the ability to launch projectile types
* that the {@link ProjectileSource} is capable of firing in vanilla.
* Any other types of projectiles *may* be implemented but are not part of the method contract.
*
* @param <T> a projectile subclass
* @param projectile class of the projectile to launch

2
paper-api/src/main/java/org/bukkit/scoreboard/Objective.java
View file

@ -86,7 +86,7 @@ public interface Objective {
*
* @return true if scores are modifiable
* @throws IllegalStateException if this objective has been unregistered
* @see Criterias#HEALTH
* @see Criteria#HEALTH
*/
boolean isModifiable();

2
paper-api/src/main/java/org/bukkit/scoreboard/Team.java
View file

@ -265,7 +265,7 @@ public interface Team extends net.kyori.adventure.audience.ForwardingAudience {
* Gets the Set of entries on the team
*
* @return entries on the team
* @throws IllegalStateException if this entries has been unregistered
* @throws IllegalStateException if this team has been unregistered
*/
@NotNull
Set<String> getEntries();

2
paper-api/src/main/java/org/bukkit/util/BoundingBox.java
View file

@ -358,7 +358,7 @@ public class BoundingBox implements Cloneable, ConfigurationSerializable {
* <p>
* Negative values will shrink the bounding box in the corresponding
* direction. Shrinking will be limited to the point where the affected
* opposite faces would meet if the they shrank at uniform speeds.
* opposite faces would meet if they shrank at uniform speeds.
*
* @param negativeX the amount of expansion in the negative x direction
* @param negativeY the amount of expansion in the negative y direction

2
paper-api/src/main/java/org/bukkit/util/CachedServerIcon.java
View file

@ -5,7 +5,7 @@ import org.bukkit.event.server.ServerListPingEvent;
import org.jetbrains.annotations.Nullable;
/**
* This is a cached version of a server-icon. It's internal representation
* This is a cached version of a server-icon. Its internal representation
* and implementation is undefined.
*
* @see Server#getServerIcon()