SPIGOT-2540: Add nullability annotations to entire Bukkit API

By: Darkyenus <darkyenus@gmail.com>

paper-api/src/main/java/org/bukkit/entity/AbstractHorse.java

@@ -2,6 +2,8 @@ package org.bukkit.entity;
 
 import org.bukkit.inventory.AbstractHorseInventory;
 import org.bukkit.inventory.InventoryHolder;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a Horse-like creature.
@@ -19,6 +21,7 @@ public interface AbstractHorse extends Animals, Vehicle, InventoryHolder, Tameab
      * @deprecated different variants are different classes
      */
     @Deprecated
+    @NotNull
     public Horse.Variant getVariant();
 
     /**
@@ -26,6 +29,7 @@ public interface AbstractHorse extends Animals, Vehicle, InventoryHolder, Tameab
      * @deprecated you are required to spawn a different entity
      */
     @Deprecated
+    @Contract("_ -> fail")
     public void setVariant(Horse.Variant variant);
 
     /**
@@ -98,6 +102,7 @@ public interface AbstractHorse extends Animals, Vehicle, InventoryHolder, Tameab
      */
     public void setJumpStrength(double strength);
 
+    @NotNull
     @Override
     public AbstractHorseInventory getInventory();
 }

paper-api/src/main/java/org/bukkit/entity/AnimalTamer.java

@@ -1,5 +1,8 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
 import java.util.UUID;
 
 public interface AnimalTamer {
@@ -9,6 +12,7 @@ public interface AnimalTamer {
      *
      * @return The name to reference on tamed animals or null if a name cannot be obtained
      */
+    @Nullable
     public String getName();
 
     /**
@@ -16,5 +20,6 @@ public interface AnimalTamer {
      *
      * @return The UUID to reference on tamed animals
      */
+    @NotNull
     public UUID getUniqueId();
 }

paper-api/src/main/java/org/bukkit/entity/Animals.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.Nullable;
+
 import java.util.UUID;
 
 /**
@@ -13,6 +15,7 @@ public interface Animals extends Ageable {
      *
      * @return uuid if set, or null
      */
+    @Nullable
     UUID getBreedCause();
 
     /**
@@ -21,7 +24,7 @@ public interface Animals extends Ageable {
      *
      * @param uuid new uuid, or null
      */
-    void setBreedCause(UUID uuid);
+    void setBreedCause(@Nullable UUID uuid);
 
     /**
      * Get whether or not this entity is in love mode and will produce

paper-api/src/main/java/org/bukkit/entity/AreaEffectCloud.java

@@ -7,6 +7,8 @@ import org.bukkit.potion.PotionData;
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
 import org.bukkit.projectiles.ProjectileSource;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents an area effect cloud which will imbue a potion effect onto
@@ -123,6 +125,7 @@ public interface AreaEffectCloud extends Entity {
      *
      * @return particle the set particle type
      */
+    @NotNull
     Particle getParticle();
 
     /**
@@ -130,7 +133,7 @@ public interface AreaEffectCloud extends Entity {
      *
      * @param particle the new particle type
      */
-    void setParticle(Particle particle);
+    void setParticle(@NotNull Particle particle);
 
     /**
      * Sets the particle which this cloud will be composed of
@@ -139,20 +142,21 @@ public interface AreaEffectCloud extends Entity {
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
      */
-    <T> void setParticle(Particle particle, T data);
+    <T> void setParticle(@NotNull Particle particle, @Nullable T data);
 
     /**
      * Sets the underlying potion data
      *
      * @param data PotionData to set the base potion state to
      */
-    void setBasePotionData(PotionData data);
+    void setBasePotionData(@NotNull PotionData data);
 
     /**
      * Returns the potion data about the base potion
      *
      * @return a PotionData object
      */
+    @NotNull
     PotionData getBasePotionData();
 
     /**
@@ -171,6 +175,7 @@ public interface AreaEffectCloud extends Entity {
      *
      * @return the immutable list of custom potion effects
      */
+    @NotNull
     List<PotionEffect> getCustomEffects();
 
     /**
@@ -181,7 +186,7 @@ public interface AreaEffectCloud extends Entity {
      * overwritten
      * @return true if the effect was added as a result of this call
      */
-    boolean addCustomEffect(PotionEffect effect, boolean overwrite);
+    boolean addCustomEffect(@NotNull PotionEffect effect, boolean overwrite);
 
     /**
      * Removes a custom potion effect from this cloud.
@@ -189,7 +194,7 @@ public interface AreaEffectCloud extends Entity {
      * @param type the potion effect type to remove
      * @return true if the an effect was removed as a result of this call
      */
-    boolean removeCustomEffect(PotionEffectType type);
+    boolean removeCustomEffect(@NotNull PotionEffectType type);
 
     /**
      * Checks for a specific custom potion effect type on this cloud.
@@ -197,7 +202,7 @@ public interface AreaEffectCloud extends Entity {
      * @param type the potion effect type to check for
      * @return true if the potion has this effect
      */
-    boolean hasCustomEffect(PotionEffectType type);
+    boolean hasCustomEffect(@Nullable PotionEffectType type);
 
     /**
      * Removes all custom potion effects from this cloud.
@@ -209,6 +214,7 @@ public interface AreaEffectCloud extends Entity {
      *
      * @return cloud color
      */
+    @NotNull
     Color getColor();
 
     /**
@@ -216,13 +222,14 @@ public interface AreaEffectCloud extends Entity {
      *
      * @param color cloud color
      */
-    void setColor(Color color);
+    void setColor(@NotNull Color color);
 
     /**
      * Retrieve the original source of this cloud.
      * 
      * @return the {@link ProjectileSource} that threw the LingeringPotion
      */
+    @Nullable
     public ProjectileSource getSource();
 
     /**
@@ -230,5 +237,5 @@ public interface AreaEffectCloud extends Entity {
      *
      * @param source the {@link ProjectileSource} that threw the LingeringPotion
      */
-    public void setSource(ProjectileSource source);
+    public void setSource(@Nullable ProjectileSource source);
 }

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

@@ -2,6 +2,8 @@ package org.bukkit.entity;
 
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.util.EulerAngle;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 public interface ArmorStand extends LivingEntity {
 
@@ -11,6 +13,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the held item
      */
+    @NotNull
     ItemStack getItemInHand();
 
     /**
@@ -19,7 +22,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param item the item to hold
      */
-    void setItemInHand(ItemStack item);
+    void setItemInHand(@Nullable ItemStack item);
 
     /**
      * Returns the item currently being worn
@@ -27,6 +30,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the worn item
      */
+    @NotNull
     ItemStack getBoots();
 
     /**
@@ -35,7 +39,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param item the item to wear
      */
-    void setBoots(ItemStack item);
+    void setBoots(@Nullable ItemStack item);
 
     /**
      * Returns the item currently being worn
@@ -43,6 +47,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the worn item
      */
+    @NotNull
     ItemStack getLeggings();
 
     /**
@@ -51,7 +56,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param item the item to wear
      */
-    void setLeggings(ItemStack item);
+    void setLeggings(@Nullable ItemStack item);
 
     /**
      * Returns the item currently being worn
@@ -59,6 +64,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the worn item
      */
+    @NotNull
     ItemStack getChestplate();
 
     /**
@@ -67,7 +73,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param item the item to wear
      */
-    void setChestplate(ItemStack item);
+    void setChestplate(@Nullable ItemStack item);
 
     /**
      * Returns the item currently being worn
@@ -75,6 +81,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the worn item
      */
+    @NotNull
     ItemStack getHelmet();
 
     /**
@@ -83,7 +90,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param item the item to wear
      */
-    void setHelmet(ItemStack item);
+    void setHelmet(@Nullable ItemStack item);
 
     /**
      * Returns the armor stand's body's
@@ -91,6 +98,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the current pose
      */
+    @NotNull
     EulerAngle getBodyPose();
 
     /**
@@ -99,7 +107,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param pose the current pose
      */
-    void setBodyPose(EulerAngle pose);
+    void setBodyPose(@NotNull EulerAngle pose);
 
     /**
      * Returns the armor stand's left arm's
@@ -107,6 +115,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the current pose
      */
+    @NotNull
     EulerAngle getLeftArmPose();
 
     /**
@@ -115,7 +124,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param pose the current pose
      */
-    void setLeftArmPose(EulerAngle pose);
+    void setLeftArmPose(@NotNull EulerAngle pose);
 
     /**
      * Returns the armor stand's right arm's
@@ -123,6 +132,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the current pose
      */
+    @NotNull
     EulerAngle getRightArmPose();
 
     /**
@@ -131,7 +141,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param pose the current pose
      */
-    void setRightArmPose(EulerAngle pose);
+    void setRightArmPose(@NotNull EulerAngle pose);
 
     /**
      * Returns the armor stand's left leg's
@@ -139,6 +149,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the current pose
      */
+    @NotNull
     EulerAngle getLeftLegPose();
 
     /**
@@ -147,7 +158,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param pose the current pose
      */
-    void setLeftLegPose(EulerAngle pose);
+    void setLeftLegPose(@NotNull EulerAngle pose);
 
     /**
      * Returns the armor stand's right leg's
@@ -155,6 +166,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the current pose
      */
+    @NotNull
     EulerAngle getRightLegPose();
 
     /**
@@ -163,7 +175,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param pose the current pose
      */
-    void setRightLegPose(EulerAngle pose);
+    void setRightLegPose(@NotNull EulerAngle pose);
 
     /**
      * Returns the armor stand's head's
@@ -171,6 +183,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @return the current pose
      */
+    @NotNull
     EulerAngle getHeadPose();
 
     /**
@@ -179,7 +192,7 @@ public interface ArmorStand extends LivingEntity {
      *
      * @param pose the current pose
      */
-    void setHeadPose(EulerAngle pose);
+    void setHeadPose(@NotNull EulerAngle pose);
 
     /**
      * Returns whether the armor stand has

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

@@ -1,6 +1,8 @@
 package org.bukkit.entity;
 
 import org.bukkit.block.Block;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents an arrow.
@@ -74,6 +76,7 @@ public interface Arrow extends Projectile {
      *
      * @return the attached block or null if not attached
      */
+    @Nullable
     public Block getAttachedBlock();
 
     /**
@@ -81,6 +84,7 @@ public interface Arrow extends Projectile {
      *
      * @return the pickup status of this arrow.
      */
+    @NotNull
     public PickupStatus getPickupStatus();
 
     /**
@@ -88,7 +92,7 @@ public interface Arrow extends Projectile {
      *
      * @param status new pickup status of this arrow.
      */
-    public void setPickupStatus(PickupStatus status);
+    public void setPickupStatus(@NotNull PickupStatus status);
 
     /**
      * Represents the pickup status of this arrow.

paper-api/src/main/java/org/bukkit/entity/Boat.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.TreeSpecies;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a boat entity.
@@ -12,6 +13,7 @@ public interface Boat extends Vehicle {
      * 
      * @return the wood type
      */
+    @NotNull
     TreeSpecies getWoodType();
 
     /**
@@ -19,7 +21,7 @@ public interface Boat extends Vehicle {
      * 
      * @param species the new wood type
      */
-    void setWoodType(TreeSpecies species);
+    void setWoodType(@NotNull TreeSpecies species);
 
     /**
      * Gets the maximum speed of a boat. The speed is unrelated to the

paper-api/src/main/java/org/bukkit/entity/Boss.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.boss.BossBar;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents the Boss Entity.
@@ -12,5 +13,6 @@ public interface Boss extends Entity {
      *
      * @return the {@link BossBar} of the entity
      */
+    @Nullable
     BossBar getBossBar();
 }

paper-api/src/main/java/org/bukkit/entity/ComplexEntityPart.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Represents a single part of a {@link ComplexLivingEntity}
  */
@@ -10,5 +12,6 @@ public interface ComplexEntityPart extends Entity {
      *
      * @return Parent complex entity
      */
+    @NotNull
     public ComplexLivingEntity getParent();
 }

paper-api/src/main/java/org/bukkit/entity/ComplexLivingEntity.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+
 import java.util.Set;
 
 /**
@@ -12,5 +14,6 @@ public interface ComplexLivingEntity extends LivingEntity {
      *
      * @return List of parts
      */
+    @NotNull
     public Set<ComplexEntityPart> getParts();
 }

paper-api/src/main/java/org/bukkit/entity/Damageable.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.attribute.Attribute;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents an {@link Entity} that has health and can take damage.
@@ -20,7 +21,7 @@ public interface Damageable extends Entity {
      * @param amount Amount of damage to deal
      * @param source Entity which to attribute this damage from
      */
-    void damage(double amount, Entity source);
+    void damage(double amount, @Nullable Entity source);
 
     /**
      * Gets the entity's health from 0 to {@link #getMaxHealth()}, where 0 is dead.

paper-api/src/main/java/org/bukkit/entity/EnderCrystal.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.Location;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * A crystal that heals nearby EnderDragons
@@ -28,6 +29,7 @@ public interface EnderCrystal extends Entity {
      *
      * @return the location that the beam is pointed to, or null if the beam is not shown
      */
+    @Nullable
     Location getBeamTarget();
 
     /**
@@ -37,5 +39,5 @@ public interface EnderCrystal extends Entity {
      * @param location the location to point the beam to
      * @throws IllegalArgumentException for differing worlds
      */
-    void setBeamTarget(Location location);
+    void setBeamTarget(@Nullable Location location);
 }

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

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Represents an Ender Dragon
  */
@@ -67,6 +69,7 @@ public interface EnderDragon extends ComplexLivingEntity, Boss {
      *
      * @return the current phase
      */
+    @NotNull
     Phase getPhase();
 
     /**
@@ -74,5 +77,5 @@ public interface EnderDragon extends ComplexLivingEntity, Boss {
      *
      * @param phase the next phase
      */
-    void setPhase(Phase phase);
+    void setPhase(@NotNull Phase phase);
 }

paper-api/src/main/java/org/bukkit/entity/EnderDragonPart.java

@@ -1,8 +1,11 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Represents an ender dragon part
  */
 public interface EnderDragonPart extends ComplexEntityPart, Damageable {
+    @NotNull
     public EnderDragon getParent();
 }

paper-api/src/main/java/org/bukkit/entity/EnderSignal.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.Location;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents an EnderSignal, which is created upon throwing an ender eye.
@@ -12,6 +13,7 @@ public interface EnderSignal extends Entity {
      *
      * @return the {@link Location} this EnderSignal is moving towards.
      */
+    @NotNull
     public Location getTargetLocation();
 
     /**
@@ -22,7 +24,7 @@ public interface EnderSignal extends Entity {
      *
      * @param location the new target location
      */
-    public void setTargetLocation(Location location);
+    public void setTargetLocation(@NotNull Location location);
 
     /**
      * Gets if the EnderSignal should drop an item on death.<br>

paper-api/src/main/java/org/bukkit/entity/Enderman.java

@@ -2,6 +2,8 @@ package org.bukkit.entity;
 
 import org.bukkit.block.data.BlockData;
 import org.bukkit.material.MaterialData;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents an Enderman.
@@ -13,6 +15,7 @@ public interface Enderman extends Monster {
      *
      * @return MaterialData containing the id and data of the block
      */
+    @NotNull
     public MaterialData getCarriedMaterial();
 
     /**
@@ -20,13 +23,14 @@ public interface Enderman extends Monster {
      *
      * @param material data to set the carried block to
      */
-    public void setCarriedMaterial(MaterialData material);
+    public void setCarriedMaterial(@NotNull MaterialData material);
 
     /**
      * Gets the data of the block that the Enderman is carrying.
      *
      * @return BlockData containing the carried block, or null if none
      */
+    @Nullable
     public BlockData getCarriedBlock();
 
     /**
@@ -34,5 +38,5 @@ public interface Enderman extends Monster {
      *
      * @param blockData data to set the carried block to, or null to remove
      */
-    public void setCarriedBlock(BlockData blockData);
+    public void setCarriedBlock(@Nullable BlockData blockData);
 }

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

@@ -1,7 +1,7 @@
 package org.bukkit.entity;
 
-import org.bukkit.Location;
 import org.bukkit.EntityEffect;
+import org.bukkit.Location;
 import org.bukkit.Nameable;
 import org.bukkit.Server;
 import org.bukkit.World;
@@ -18,6 +18,9 @@ import java.util.UUID;
 import org.bukkit.block.PistonMoveReaction;
 import org.bukkit.command.CommandSender;
 import org.bukkit.event.player.PlayerTeleportEvent.TeleportCause;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a base entity in the world
@@ -29,6 +32,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @return a new copy of Location containing the position of this entity
      */
+    @NotNull
     public Location getLocation();
 
     /**
@@ -40,20 +44,23 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param loc the location to copy into
      * @return The Location object provided or null
      */
-    public Location getLocation(Location loc);
+    @Contract("null -> null; !null -> !null")
+    @Nullable
+    public Location getLocation(@Nullable Location loc);
 
     /**
      * Sets this entity's velocity
      *
      * @param velocity New velocity to travel with
      */
-    public void setVelocity(Vector velocity);
+    public void setVelocity(@NotNull Vector velocity);
 
     /**
      * Gets this entity's current velocity
      *
      * @return Current traveling velocity of this entity
      */
+    @NotNull
     public Vector getVelocity();
 
     /**
@@ -78,6 +85,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @return the entity's current bounding box
      */
+    @NotNull
     public BoundingBox getBoundingBox();
 
     /**
@@ -94,6 +102,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @return World
      */
+    @NotNull
     public World getWorld();
 
     /**
@@ -103,7 +112,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param location New location to teleport this entity to
      * @return <code>true</code> if the teleport was successful
      */
-    public boolean teleport(Location location);
+    public boolean teleport(@NotNull Location location);
 
     /**
      * Teleports this entity to the given location. If this entity is riding a
@@ -113,7 +122,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param cause The cause of this teleportation
      * @return <code>true</code> if the teleport was successful
      */
-    public boolean teleport(Location location, TeleportCause cause);
+    public boolean teleport(@NotNull Location location, @NotNull TeleportCause cause);
 
     /**
      * Teleports this entity to the target Entity. If this entity is riding a
@@ -122,7 +131,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param destination Entity to teleport this entity to
      * @return <code>true</code> if the teleport was successful
      */
-    public boolean teleport(Entity destination);
+    public boolean teleport(@NotNull Entity destination);
 
     /**
      * Teleports this entity to the target Entity. If this entity is riding a
@@ -132,7 +141,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param cause The cause of this teleportation
      * @return <code>true</code> if the teleport was successful
      */
-    public boolean teleport(Entity destination, TeleportCause cause);
+    public boolean teleport(@NotNull Entity destination, @NotNull TeleportCause cause);
 
     /**
      * Returns a list of entities within a bounding box centered around this
@@ -143,6 +152,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param z 1/2 the size of the box along z axis
      * @return {@code List<Entity>} List of entities nearby
      */
+    @NotNull
     public List<org.bukkit.entity.Entity> getNearbyEntities(double x, double y, double z);
 
     /**
@@ -200,6 +210,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @return Server instance running this Entity
      */
+    @NotNull
     public Server getServer();
 
     /**
@@ -242,6 +253,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * {@link #getPassengers()}
      */
     @Deprecated
+    @Nullable
     public Entity getPassenger();
 
     /**
@@ -253,7 +265,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * {@link #getPassengers()}
      */
     @Deprecated
-    public boolean setPassenger(Entity passenger);
+    public boolean setPassenger(@NotNull Entity passenger);
 
     /**
      * Gets a list of passengers of this vehicle.
@@ -263,6 +275,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @return list of entities corresponding to current passengers.
      */
+    @NotNull
     public List<Entity> getPassengers();
 
     /**
@@ -271,7 +284,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param passenger The passenger to add
      * @return false if it could not be done for whatever reason
      */
-    public boolean addPassenger(Entity passenger);
+    public boolean addPassenger(@NotNull Entity passenger);
 
     /**
      * Remove a passenger from the vehicle.
@@ -279,7 +292,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param passenger The passenger to remove
      * @return false if it could not be done for whatever reason
      */
-    public boolean removePassenger(Entity passenger);
+    public boolean removePassenger(@NotNull Entity passenger);
 
     /**
      * Check if a vehicle has passengers.
@@ -314,7 +327,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @param event a {@link EntityDamageEvent}
      */
-    public void setLastDamageCause(EntityDamageEvent event);
+    public void setLastDamageCause(@Nullable EntityDamageEvent event);
 
     /**
      * Retrieve the last {@link EntityDamageEvent} inflicted on this entity.
@@ -323,6 +336,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @return the last known {@link EntityDamageEvent} or null if hitherto
      *     unharmed
      */
+    @Nullable
     public EntityDamageEvent getLastDamageCause();
 
     /**
@@ -330,6 +344,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @return unique id
      */
+    @NotNull
     public UUID getUniqueId();
 
     /**
@@ -360,13 +375,14 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @param type Effect to play.
      */
-    public void playEffect(EntityEffect type);
+    public void playEffect(@NotNull EntityEffect type);
 
     /**
      * Get the type of the entity.
      *
      * @return The entity type.
      */
+    @NotNull
     public EntityType getType();
 
     /**
@@ -391,6 +407,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @return The current vehicle.
      */
+    @Nullable
     public Entity getVehicle();
 
     /**
@@ -496,6 +513,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      *
      * @return a set of tags for this entity
      */
+    @NotNull
     Set<String> getScoreboardTags();
 
     /**
@@ -506,7 +524,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param tag the tag to add
      * @return true if the tag was successfully added
      */
-    boolean addScoreboardTag(String tag);
+    boolean addScoreboardTag(@NotNull String tag);
 
     /**
      * Removes a given tag from this entity.
@@ -514,13 +532,14 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @param tag the tag to remove
      * @return true if the tag was successfully removed
      */
-    boolean removeScoreboardTag(String tag);
+    boolean removeScoreboardTag(@NotNull String tag);
 
     /**
      * Returns the reaction of the entity when moved by a piston.
      *
      * @return reaction
      */
+    @NotNull
     PistonMoveReaction getPistonMoveReaction();
 
     /**
@@ -537,5 +556,6 @@ public interface Entity extends Metadatable, CommandSender, Nameable {
      * @see Hanging
      * @see Directional#getFacing()
      */
+    @NotNull
     BlockFace getFacing();
 }

paper-api/src/main/java/org/bukkit/entity/EntityType.java

@@ -14,6 +14,8 @@ import org.bukkit.inventory.ItemStack;
 import org.bukkit.Location;
 import org.bukkit.World;
 import org.bukkit.potion.PotionEffectType;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Nullable;
 
 public enum EntityType {
 
@@ -309,11 +311,11 @@ public enum EntityType {
         NAME_MAP.put("ender_crystal", ENDER_CRYSTAL);
     }
 
-    private EntityType(String name, Class<? extends Entity> clazz, int typeId) {
+    private EntityType(@Nullable String name, @Nullable Class<? extends Entity> clazz, int typeId) {
         this(name, clazz, typeId, true);
     }
 
-    private EntityType(String name, Class<? extends Entity> clazz, int typeId, boolean independent) {
+    private EntityType(@Nullable String name, @Nullable Class<? extends Entity> clazz, int typeId, boolean independent) {
         this.name = name;
         this.clazz = clazz;
         this.typeId = (short) typeId;
@@ -329,10 +331,12 @@ public enum EntityType {
      * @deprecated Magic value
      */
     @Deprecated
+    @Nullable
     public String getName() {
         return name;
     }
 
+    @Nullable
     public Class<? extends Entity> getEntityClass() {
         return clazz;
     }
@@ -354,7 +358,9 @@ public enum EntityType {
      * @deprecated Magic value
      */
     @Deprecated
-    public static EntityType fromName(String name) {
+    @Contract("null -> null")
+    @Nullable
+    public static EntityType fromName(@Nullable String name) {
         if (name == null) {
             return null;
         }
@@ -368,6 +374,7 @@ public enum EntityType {
      * @deprecated Magic value
      */
     @Deprecated
+    @Nullable
     public static EntityType fromId(int id) {
         if (id > Short.MAX_VALUE) {
             return null;

paper-api/src/main/java/org/bukkit/entity/Evoker.java

@@ -1,5 +1,8 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
 /**
  * Represents an Evoker "Illager".
  */
@@ -49,6 +52,7 @@ public interface Evoker extends Spellcaster {
      *
      */
     @Deprecated
+    @NotNull
     Spell getCurrentSpell();
 
     /**
@@ -59,5 +63,5 @@ public interface Evoker extends Spellcaster {
      * entities.
      */
     @Deprecated
-    void setCurrentSpell(Spell spell);
+    void setCurrentSpell(@Nullable Spell spell);
 }

paper-api/src/main/java/org/bukkit/entity/EvokerFangs.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.Nullable;
+
 /**
  * Represents Evoker Fangs.
  */
@@ -10,6 +12,7 @@ public interface EvokerFangs extends Entity {
      *
      * @return the {@link LivingEntity} which summoned the fangs
      */
+    @Nullable
     LivingEntity getOwner();
 
     /**
@@ -17,5 +20,5 @@ public interface EvokerFangs extends Entity {
      *
      * @param owner the {@link LivingEntity} which summoned the fangs
      */
-    void setOwner(LivingEntity owner);
+    void setOwner(@Nullable LivingEntity owner);
 }

paper-api/src/main/java/org/bukkit/entity/FallingBlock.java

@@ -2,6 +2,7 @@ package org.bukkit.entity;
 
 import org.bukkit.Material;
 import org.bukkit.block.data.BlockData;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a falling block
@@ -15,6 +16,7 @@ public interface FallingBlock extends Entity {
      * @deprecated use {@link #getBlockData()}
      */
     @Deprecated
+    @NotNull
     Material getMaterial();
 
     /**
@@ -22,6 +24,7 @@ public interface FallingBlock extends Entity {
      *
      * @return data of the block
      */
+    @NotNull
     BlockData getBlockData();
 
     /**

paper-api/src/main/java/org/bukkit/entity/Fireball.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.util.Vector;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a Fireball.
@@ -12,13 +13,14 @@ public interface Fireball extends Projectile, Explosive {
      *
      * @param direction the direction this fireball is flying toward
      */
-    public void setDirection(Vector direction);
+    public void setDirection(@NotNull Vector direction);
 
     /**
      * Retrieve the direction this fireball is heading toward
      *
      * @return the direction
      */
+    @NotNull
     public Vector getDirection();
 
 }

paper-api/src/main/java/org/bukkit/entity/Firework.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.inventory.meta.FireworkMeta;
+import org.jetbrains.annotations.NotNull;
 
 public interface Firework extends Entity {
 
@@ -9,6 +10,7 @@ public interface Firework extends Entity {
      *
      * @return A copy of the current Firework meta
      */
+    @NotNull
     FireworkMeta getFireworkMeta();
 
     /**
@@ -16,7 +18,7 @@ public interface Firework extends Entity {
      *
      * @param meta The FireworkMeta to apply
      */
-    void setFireworkMeta(FireworkMeta meta);
+    void setFireworkMeta(@NotNull FireworkMeta meta);
 
     /**
      * Cause this firework to explode at earliest opportunity, as if it has no

paper-api/src/main/java/org/bukkit/entity/Hanging.java

@@ -2,6 +2,7 @@ package org.bukkit.entity;
 
 import org.bukkit.block.BlockFace;
 import org.bukkit.material.Attachable;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a Hanging entity
@@ -18,5 +19,5 @@ public interface Hanging extends Entity, Attachable {
      * @return False if force was false and there was no block for it to
      *     attach to in order to face the given direction.
      */
-    public boolean setFacingDirection(BlockFace face, boolean force);
+    public boolean setFacingDirection(@NotNull BlockFace face, boolean force);
 }

paper-api/src/main/java/org/bukkit/entity/Horse.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.inventory.HorseInventory;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a Horse.
@@ -109,6 +110,7 @@ public interface Horse extends AbstractHorse {
      *
      * @return a {@link Color} representing the horse's group
      */
+    @NotNull
     public Color getColor();
 
     /**
@@ -119,7 +121,7 @@ public interface Horse extends AbstractHorse {
      *
      * @param color a {@link Color} for this horse
      */
-    public void setColor(Color color);
+    public void setColor(@NotNull Color color);
 
     /**
      * Gets the horse's style.
@@ -130,6 +132,7 @@ public interface Horse extends AbstractHorse {
      *
      * @return a {@link Style} representing the horse's style
      */
+    @NotNull
     public Style getStyle();
 
     /**
@@ -141,7 +144,7 @@ public interface Horse extends AbstractHorse {
      *
      * @param style a {@link Style} for this horse
      */
-    public void setStyle(Style style);
+    public void setStyle(@NotNull Style style);
 
     /**
      * @return carrying chest status
@@ -157,6 +160,7 @@ public interface Horse extends AbstractHorse {
     @Deprecated
     public void setCarryingChest(boolean chest);
 
+    @NotNull
     @Override
     public HorseInventory getInventory();
 }

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

@@ -12,6 +12,8 @@ import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.PlayerInventory;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a human entity, such as an NPC or a player
@@ -23,6 +25,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @return Player name
      */
+    @NotNull
+    @Override
     public String getName();
 
     /**
@@ -31,6 +35,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @return The inventory of the player, this also contains the armor
      *     slots.
      */
+    @NotNull
+    @Override
     public PlayerInventory getInventory();
 
     /**
@@ -38,6 +44,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @return The EnderChest of the player
      */
+    @NotNull
     public Inventory getEnderChest();
 
     /**
@@ -45,6 +52,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @return the players main hand
      */
+    @NotNull
     public MainHand getMainHand();
 
     /**
@@ -55,7 +63,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param value The value to set the property to.
      * @return True if the property was successfully set.
      */
-    public boolean setWindowProperty(InventoryView.Property prop, int value);
+    public boolean setWindowProperty(@NotNull InventoryView.Property prop, int value);
 
     /**
      * Gets the inventory view the player is currently viewing. If they do not
@@ -63,6 +71,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @return The inventory view.
      */
+    @NotNull
     public InventoryView getOpenInventory();
 
     /**
@@ -72,7 +81,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param inventory The inventory to open
      * @return The newly opened inventory view
      */
-    public InventoryView openInventory(Inventory inventory);
+    @Nullable
+    public InventoryView openInventory(@NotNull Inventory inventory);
 
     /**
      * Opens an empty workbench inventory window with the player's inventory
@@ -85,7 +95,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @return The newly opened inventory view, or null if it could not be
      *     opened.
      */
-    public InventoryView openWorkbench(Location location, boolean force);
+    @Nullable
+    public InventoryView openWorkbench(@Nullable Location location, boolean force);
 
     /**
      * Opens an empty enchanting inventory window with the player's inventory
@@ -98,14 +109,15 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @return The newly opened inventory view, or null if it could not be
      *     opened.
      */
-    public InventoryView openEnchanting(Location location, boolean force);
+    @Nullable
+    public InventoryView openEnchanting(@Nullable Location location, boolean force);
 
     /**
      * Opens an inventory window to the specified inventory view.
      *
      * @param inventory The view to open
      */
-    public void openInventory(InventoryView inventory);
+    public void openInventory(@NotNull InventoryView inventory);
 
     /**
      * Starts a trade between the player and the villager.
@@ -118,7 +130,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @return The newly opened inventory view, or null if it could not be
      * opened.
      */
-    public InventoryView openMerchant(Villager trader, boolean force);
+    @Nullable
+    public InventoryView openMerchant(@NotNull Villager trader, boolean force);
 
     /**
      * Starts a trade between the player and the merchant.
@@ -131,7 +144,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @return The newly opened inventory view, or null if it could not be
      * opened.
      */
-    public InventoryView openMerchant(Merchant merchant, boolean force);
+    @Nullable
+    public InventoryView openMerchant(@NotNull Merchant merchant, boolean force);
 
     /**
      * Force-closes the currently open inventory view for this player, if any.
@@ -146,6 +160,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * methods in {@link PlayerInventory}.
      */
     @Deprecated
+    @NotNull
     public ItemStack getItemInHand();
 
     /**
@@ -157,7 +172,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * methods in {@link PlayerInventory}.
      */
     @Deprecated
-    public void setItemInHand(ItemStack item);
+    public void setItemInHand(@Nullable ItemStack item);
 
     /**
      * Returns the ItemStack currently on your cursor, can be empty. Will
@@ -165,6 +180,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @return The ItemStack of the item you are currently moving around.
      */
+    @NotNull
     public ItemStack getItemOnCursor();
 
     /**
@@ -174,7 +190,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @param item The ItemStack which will end up in the hand
      */
-    public void setItemOnCursor(ItemStack item);
+    public void setItemOnCursor(@Nullable ItemStack item);
 
     /**
      * Check whether a cooldown is active on the specified material.
@@ -182,7 +198,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param material the material to check
      * @return if a cooldown is active on the material
      */
-    public boolean hasCooldown(Material material);
+    public boolean hasCooldown(@NotNull Material material);
 
     /**
      * Get the cooldown time in ticks remaining for the specified material.
@@ -190,7 +206,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param material the material to check
      * @return the remaining cooldown time in ticks
      */
-    public int getCooldown(Material material);
+    public int getCooldown(@NotNull Material material);
 
     /**
      * Set a cooldown on the specified material for a certain amount of ticks.
@@ -205,7 +221,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param material the material to set the cooldown for
      * @param ticks the amount of ticks to set or 0 to remove
      */
-    public void setCooldown(Material material, int ticks);
+    public void setCooldown(@NotNull Material material, int ticks);
 
     /**
      * Returns whether this player is slumbering.
@@ -227,6 +243,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @return Bed Spawn Location if bed exists, otherwise null.
      */
+    @Nullable
     public Location getBedSpawnLocation();
 
     /**
@@ -234,7 +251,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @param location where to set the respawn location
      */
-    public void setBedSpawnLocation(Location location);
+    public void setBedSpawnLocation(@Nullable Location location);
 
     /**
      * Sets the Location where the player will spawn at their bed.
@@ -243,7 +260,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param force whether to forcefully set the respawn location even if a
      *     valid bed is not present
      */
-    public void setBedSpawnLocation(Location location, boolean force);
+    public void setBedSpawnLocation(@Nullable Location location, boolean force);
 
     /**
      * Attempts to make the entity sleep at the given location.
@@ -257,7 +274,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * normally possible
      * @return whether the sleep was successful
      */
-    public boolean sleep(Location location, boolean force);
+    public boolean sleep(@NotNull Location location, boolean force);
 
     /**
      * Causes the player to wakeup if they are currently sleeping.
@@ -274,6 +291,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @return location
      * @throws IllegalStateException if not sleeping
      */
+    @NotNull
     public Location getBedLocation();
 
     /**
@@ -281,6 +299,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @return Current game mode
      */
+    @NotNull
     public GameMode getGameMode();
 
     /**
@@ -288,7 +307,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @param mode New game mode
      */
-    public void setGameMode(GameMode mode);
+    public void setGameMode(@NotNull GameMode mode);
 
     /**
      * Check if the player is currently blocking (ie with a shield).
@@ -321,7 +340,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *
      * @return whether or not the recipe was newly discovered
      */
-    public boolean discoverRecipe(NamespacedKey recipe);
+    public boolean discoverRecipe(@NotNull NamespacedKey recipe);
 
     /**
      * Discover a collection of recipes for this player such that they have not
@@ -335,7 +354,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * none were newly discovered and a number equal to {@code recipes.size()}
      * indicates that all were new
      */
-    public int discoverRecipes(Collection<NamespacedKey> recipes);
+    public int discoverRecipes(@NotNull Collection<NamespacedKey> recipes);
 
     /**
      * Undiscover a recipe for this player such that it has already been
@@ -347,7 +366,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @return whether or not the recipe was successfully undiscovered (i.e. it
      * was previously discovered)
      */
-    public boolean undiscoverRecipe(NamespacedKey recipe);
+    public boolean undiscoverRecipe(@NotNull NamespacedKey recipe);
 
     /**
      * Undiscover a collection of recipes for this player such that they have
@@ -361,7 +380,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * were undiscovered and a number equal to {@code recipes.size()} indicates
      * that all were undiscovered
      */
-    public int undiscoverRecipes(Collection<NamespacedKey> recipes);
+    public int undiscoverRecipes(@NotNull Collection<NamespacedKey> recipes);
 
     /**
      * Gets the entity currently perched on the left shoulder or null if no
@@ -375,6 +394,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * serialized entities in Bukkit. Use with care.
      */
     @Deprecated
+    @Nullable
     public Entity getShoulderEntityLeft();
 
     /**
@@ -392,7 +412,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * serialized entities in Bukkit. Use with care.
      */
     @Deprecated
-    public void setShoulderEntityLeft(Entity entity);
+    public void setShoulderEntityLeft(@Nullable Entity entity);
 
     /**
      * Gets the entity currently perched on the right shoulder or null if no
@@ -406,6 +426,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * serialized entities in Bukkit. Use with care.
      */
     @Deprecated
+    @Nullable
     public Entity getShoulderEntityRight();
 
     /**
@@ -423,5 +444,5 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * serialized entities in Bukkit. Use with care.
      */
     @Deprecated
-    public void setShoulderEntityRight(Entity entity);
+    public void setShoulderEntityRight(@Nullable Entity entity);
 }

paper-api/src/main/java/org/bukkit/entity/Item.java

@@ -1,9 +1,11 @@
 package org.bukkit.entity;
 
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
- * Represents an Item.
+ * Represents a dropped item.
  */
 public interface Item extends Entity {
 
@@ -12,6 +14,7 @@ public interface Item extends Entity {
      *
      * @return An item stack.
      */
+    @NotNull
     public ItemStack getItemStack();
 
     /**
@@ -19,7 +22,7 @@ public interface Item extends Entity {
      *
      * @param stack An item stack.
      */
-    public void setItemStack(ItemStack stack);
+    public void setItemStack(@Nullable ItemStack stack);
 
     /**
      * Gets the delay before this Item is available to be picked up by players

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

@@ -2,6 +2,8 @@ package org.bukkit.entity;
 
 import org.bukkit.Rotation;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents an Item Frame
@@ -13,6 +15,7 @@ public interface ItemFrame extends Hanging {
      *
      * @return a defensive copy the item in this item frame
      */
+    @NotNull
     public ItemStack getItem();
 
     /**
@@ -20,7 +23,7 @@ public interface ItemFrame extends Hanging {
      *
      * @param item the new item
      */
-    public void setItem(ItemStack item);
+    public void setItem(@Nullable ItemStack item);
 
     /**
      * Set the item in this frame
@@ -28,13 +31,14 @@ public interface ItemFrame extends Hanging {
      * @param item the new item
      * @param playSound whether or not to play the item placement sound
      */
-    public void setItem(ItemStack item, boolean playSound);
+    public void setItem(@Nullable ItemStack item, boolean playSound);
 
     /**
      * Get the rotation of the frame's item
      *
      * @return the direction
      */
+    @NotNull
     public Rotation getRotation();
 
     /**
@@ -43,5 +47,5 @@ public interface ItemFrame extends Hanging {
      * @param rotation the new rotation
      * @throws IllegalArgumentException if rotation is null
      */
-    public void setRotation(Rotation rotation) throws IllegalArgumentException;
+    public void setRotation(@NotNull Rotation rotation) throws IllegalArgumentException;
 }

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

@@ -16,6 +16,8 @@ import org.bukkit.potion.PotionEffectType;
 import org.bukkit.projectiles.ProjectileSource;
 import org.bukkit.util.RayTraceResult;
 import org.bukkit.util.Vector;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a living entity, such as a monster or player
@@ -43,6 +45,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      *
      * @return a location at the eyes of the living entity
      */
+    @NotNull
     public Location getEyeLocation();
 
     /**
@@ -58,7 +61,8 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @return list containing all blocks along the living entity's line of
      *     sight
      */
-    public List<Block> getLineOfSight(Set<Material> transparent, int maxDistance);
+    @NotNull
+    public List<Block> getLineOfSight(@Nullable Set<Material> transparent, int maxDistance);
 
     /**
      * Gets the block that the living entity has targeted.
@@ -73,7 +77,8 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      *     by server by at least 100 blocks, no less)
      * @return block that the living entity has targeted
      */
-    public Block getTargetBlock(Set<Material> transparent, int maxDistance);
+    @NotNull
+    public Block getTargetBlock(@Nullable Set<Material> transparent, int maxDistance);
 
     /**
      * Gets the last two blocks along the living entity's line of sight.
@@ -88,7 +93,8 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @return list containing the last 2 blocks along the living entity's
      *     line of sight
      */
-    public List<Block> getLastTwoTargetBlocks(Set<Material> transparent, int maxDistance);
+    @NotNull
+    public List<Block> getLastTwoTargetBlocks(@Nullable Set<Material> transparent, int maxDistance);
 
     /**
      * Gets the block that the living entity has targeted.
@@ -103,6 +109,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @return block that the living entity has targeted
      * @see #getTargetBlockExact(int, org.bukkit.FluidCollisionMode)
      */
+    @Nullable
     public Block getTargetBlockExact(int maxDistance);
 
     /**
@@ -118,7 +125,8 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @return block that the living entity has targeted
      * @see #rayTraceBlocks(double, FluidCollisionMode)
      */
-    public Block getTargetBlockExact(int maxDistance, FluidCollisionMode fluidCollisionMode);
+    @Nullable
+    public Block getTargetBlockExact(int maxDistance, @NotNull FluidCollisionMode fluidCollisionMode);
 
     /**
      * Performs a ray trace that provides information on the targeted block.
@@ -134,6 +142,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      *     is no targeted block in range
      * @see #rayTraceBlocks(double, FluidCollisionMode)
      */
+    @Nullable
     public RayTraceResult rayTraceBlocks(double maxDistance);
 
     /**
@@ -150,7 +159,8 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      *     is no targeted block in range
      * @see World#rayTraceBlocks(Location, Vector, double, FluidCollisionMode)
      */
-    public RayTraceResult rayTraceBlocks(double maxDistance, FluidCollisionMode fluidCollisionMode);
+    @Nullable
+    public RayTraceResult rayTraceBlocks(double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode);
 
     /**
      * Returns the amount of air that the living entity has remaining, in
@@ -237,6 +247,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      *
      * @return killer player, or null if none found
      */
+    @Nullable
     public Player getKiller();
 
     /**
@@ -248,7 +259,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @param effect PotionEffect to be added
      * @return whether the effect could be added
      */
-    public boolean addPotionEffect(PotionEffect effect);
+    public boolean addPotionEffect(@NotNull PotionEffect effect);
 
     /**
      * Adds the given {@link PotionEffect} to the living entity.
@@ -260,7 +271,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @param force whether conflicting effects should be removed
      * @return whether the effect could be added
      */
-    public boolean addPotionEffect(PotionEffect effect, boolean force);
+    public boolean addPotionEffect(@NotNull PotionEffect effect, boolean force);
 
     /**
      * Attempts to add all of the given {@link PotionEffect} to the living
@@ -269,7 +280,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @param effects the effects to add
      * @return whether all of the effects could be added
      */
-    public boolean addPotionEffects(Collection<PotionEffect> effects);
+    public boolean addPotionEffects(@NotNull Collection<PotionEffect> effects);
 
     /**
      * Returns whether the living entity already has an existing effect of
@@ -278,7 +289,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @param type the potion type to check
      * @return whether the living entity has this potion effect active on them
      */
-    public boolean hasPotionEffect(PotionEffectType type);
+    public boolean hasPotionEffect(@NotNull PotionEffectType type);
 
     /**
      * Returns the active {@link PotionEffect} of the specified type.
@@ -288,14 +299,15 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @param type the potion type to check
      * @return the effect active on this entity, or null if not active.
      */
-    public PotionEffect getPotionEffect(PotionEffectType type);
+    @Nullable
+    public PotionEffect getPotionEffect(@NotNull PotionEffectType type);
 
     /**
      * Removes any effects present of the given {@link PotionEffectType}.
      *
      * @param type the potion type to remove
      */
-    public void removePotionEffect(PotionEffectType type);
+    public void removePotionEffect(@NotNull PotionEffectType type);
 
     /**
      * Returns all currently active {@link PotionEffect}s on the living
@@ -303,6 +315,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      *
      * @return a collection of {@link PotionEffect}s
      */
+    @NotNull
     public Collection<PotionEffect> getActivePotionEffects();
 
     /**
@@ -314,7 +327,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @param other the entity to determine line of sight to
      * @return true if there is a line of sight, false if not
      */
-    public boolean hasLineOfSight(Entity other);
+    public boolean hasLineOfSight(@NotNull Entity other);
 
     /**
      * Returns if the living entity despawns when away from players or not.
@@ -338,6 +351,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      *
      * @return the living entity's inventory
      */
+    @Nullable
     public EntityEquipment getEquipment();
 
     /**
@@ -367,6 +381,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @return the entity holding the leash
      * @throws IllegalStateException if not currently leashed
      */
+    @NotNull
     public Entity getLeashHolder() throws IllegalStateException;
 
     /**
@@ -376,10 +391,10 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * Non-living entities excluding leashes will not persist as leash
      * holders.
      *
-     * @param holder the entity to leash this entity to
+     * @param holder the entity to leash this entity to, or null to unleash
      * @return whether the operation was successful
      */
-    public boolean setLeashHolder(Entity holder);
+    public boolean setLeashHolder(@Nullable Entity holder);
 
     /**
      * Checks to see if an entity is gliding, such as using an Elytra.

paper-api/src/main/java/org/bukkit/entity/Llama.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.inventory.LlamaInventory;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a Llama.
@@ -35,6 +36,7 @@ public interface Llama extends ChestedHorse {
      *
      * @return a {@link Color} representing the llama's color
      */
+    @NotNull
     Color getColor();
 
     /**
@@ -42,7 +44,7 @@ public interface Llama extends ChestedHorse {
      *
      * @param color a {@link Color} for this llama
      */
-    void setColor(Color color);
+    void setColor(@NotNull Color color);
 
     /**
      * Gets the llama's strength. A higher strength llama will have more
@@ -61,6 +63,7 @@ public interface Llama extends ChestedHorse {
      */
     void setStrength(int strength);
 
+    @NotNull
     @Override
     LlamaInventory getInventory();
 }

paper-api/src/main/java/org/bukkit/entity/Minecart.java

@@ -3,6 +3,8 @@ package org.bukkit.entity;
 import org.bukkit.block.data.BlockData;
 import org.bukkit.material.MaterialData;
 import org.bukkit.util.Vector;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a minecart entity.
@@ -62,6 +64,7 @@ public interface Minecart extends Vehicle {
      *
      * @return The vector factor
      */
+    @NotNull
     public Vector getFlyingVelocityMod();
 
     /**
@@ -71,7 +74,7 @@ public interface Minecart extends Vehicle {
      *
      * @param flying velocity modifier vector
      */
-    public void setFlyingVelocityMod(Vector flying);
+    public void setFlyingVelocityMod(@NotNull Vector flying);
 
     /**
      * Gets the derailed velocity modifier. Used for minecarts that are on the
@@ -81,6 +84,7 @@ public interface Minecart extends Vehicle {
      *
      * @return derailed visible speed
      */
+    @NotNull
     public Vector getDerailedVelocityMod();
 
     /**
@@ -90,7 +94,7 @@ public interface Minecart extends Vehicle {
      *
      * @param derailed visible speed
      */
-    public void setDerailedVelocityMod(Vector derailed);
+    public void setDerailedVelocityMod(@NotNull Vector derailed);
 
     /**
      * Sets the display block for this minecart.
@@ -98,7 +102,7 @@ public interface Minecart extends Vehicle {
      *
      * @param material the material to set as display block.
      */
-    public void setDisplayBlock(MaterialData material);
+    public void setDisplayBlock(@Nullable MaterialData material);
 
     /**
      * Gets the display block for this minecart.
@@ -106,6 +110,7 @@ public interface Minecart extends Vehicle {
      *
      * @return the block displayed by this minecart.
      */
+    @NotNull
     public MaterialData getDisplayBlock();
 
     /**
@@ -114,7 +119,7 @@ public interface Minecart extends Vehicle {
      *
      * @param blockData the material to set as display block.
      */
-    public void setDisplayBlockData(BlockData blockData);
+    public void setDisplayBlockData(@Nullable BlockData blockData);
 
     /**
      * Gets the display block for this minecart.
@@ -122,6 +127,7 @@ public interface Minecart extends Vehicle {
      *
      * @return the block displayed by this minecart.
      */
+    @NotNull
     public BlockData getDisplayBlockData();
 
     /**

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

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.loot.Lootable;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a Mob. Mobs are living entities with simple AI.
@@ -15,12 +16,13 @@ public interface Mob extends LivingEntity, Lootable {
      *
      * @param target New LivingEntity to target, or null to clear the target
      */
-    public void setTarget(LivingEntity target);
+    public void setTarget(@Nullable LivingEntity target);
 
     /**
      * Gets the current target of this Mob
      *
      * @return Current target of this creature, or null if none exists
      */
+    @Nullable
     public LivingEntity getTarget();
 }

paper-api/src/main/java/org/bukkit/entity/Ocelot.java

@@ -1,6 +1,9 @@
 
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
 /**
  * A wild tameable cat
  */
@@ -11,6 +14,7 @@ public interface Ocelot extends Animals, Tameable, Sittable {
      *
      * @return Type of the cat.
      */
+    @NotNull
     public Type getCatType();
 
     /**
@@ -18,7 +22,7 @@ public interface Ocelot extends Animals, Tameable, Sittable {
      *
      * @param type New type of this cat.
      */
-    public void setCatType(Type type);
+    public void setCatType(@NotNull Type type);
 
     /**
      * Represents the various different cat types there are.
@@ -61,6 +65,7 @@ public interface Ocelot extends Animals, Tameable, Sittable {
          * @deprecated Magic value
          */
         @Deprecated
+        @Nullable
         public static Type getType(int id) {
             return (id >= types.length) ? null : types[id];
         }

paper-api/src/main/java/org/bukkit/entity/Painting.java

@@ -2,6 +2,7 @@ package org.bukkit.entity;
 
 import org.bukkit.Art;
 import org.bukkit.event.hanging.HangingBreakEvent;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a Painting.
@@ -13,6 +14,7 @@ public interface Painting extends Hanging {
      *
      * @return The art
      */
+    @NotNull
     public Art getArt();
 
     /**
@@ -22,7 +24,7 @@ public interface Painting extends Hanging {
      * @return False if the new art won't fit at the painting's current
      *     location
      */
-    public boolean setArt(Art art);
+    public boolean setArt(@NotNull Art art);
 
     /**
      * Set the art on this painting
@@ -35,5 +37,5 @@ public interface Painting extends Hanging {
      * @return False if force was false and the new art won't fit at the
      *     painting's current location
      */
-    public boolean setArt(Art art, boolean force);
+    public boolean setArt(@NotNull Art art, boolean force);
 }

paper-api/src/main/java/org/bukkit/entity/Parrot.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Represents a Parrot.
  */
@@ -10,6 +12,7 @@ public interface Parrot extends Animals, Tameable, Sittable {
      *
      * @return parrot variant
      */
+    @NotNull
     public Variant getVariant();
 
     /**
@@ -17,7 +20,7 @@ public interface Parrot extends Animals, Tameable, Sittable {
      *
      * @param variant parrot variant
      */
-    public void setVariant(Variant variant);
+    public void setVariant(@NotNull Variant variant);
 
     /**
      * Represents the variant of a parrot - ie its color.

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

@@ -3,7 +3,6 @@ package org.bukkit.entity;
 import java.net.InetSocketAddress;
 
 import org.bukkit.Achievement;
-import org.bukkit.ChatColor;
 import org.bukkit.Effect;
 import org.bukkit.GameMode;
 import org.bukkit.Instrument;
@@ -25,6 +24,8 @@ import org.bukkit.map.MapView;
 import org.bukkit.plugin.Plugin;
 import org.bukkit.plugin.messaging.PluginMessageRecipient;
 import org.bukkit.scoreboard.Scoreboard;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a player, connected or not
@@ -40,6 +41,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @return the friendly name
      */
+    @NotNull
     public String getDisplayName();
 
     /**
@@ -51,13 +53,14 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @param name The new display name.
      */
-    public void setDisplayName(String name);
+    public void setDisplayName(@Nullable String name);
 
     /**
      * Gets the name that is shown on the player list.
      *
      * @return the player list name
      */
+    @NotNull
     public String getPlayerListName();
 
     /**
@@ -67,13 +70,14 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @param name new player list name
      */
-    public void setPlayerListName(String name);
+    public void setPlayerListName(@Nullable String name);
 
     /**
      * Gets the currently displayed player list header for this player.
      *
      * @return player list header or null
      */
+    @Nullable
     public String getPlayerListHeader();
 
     /**
@@ -81,6 +85,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @return player list header or null
      */
+    @Nullable
     public String getPlayerListFooter();
 
     /**
@@ -88,14 +93,14 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @param header player list header, null for empty
      */
-    public void setPlayerListHeader(String header);
+    public void setPlayerListHeader(@Nullable String header);
 
     /**
      * Sets the currently displayed player list footer for this player.
      *
      * @param footer player list footer, null for empty
      */
-    public void setPlayerListFooter(String footer);
+    public void setPlayerListFooter(@Nullable String footer);
 
     /**
      * Sets the currently displayed player list header and footer for this
@@ -104,20 +109,21 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param header player list header, null for empty
      * @param footer player list footer, null for empty
      */
-    public void setPlayerListHeaderFooter(String header, String footer);
+    public void setPlayerListHeaderFooter(@Nullable String header, @Nullable String footer);
 
     /**
      * Set the target of the player's compass.
      *
      * @param loc Location to point to
      */
-    public void setCompassTarget(Location loc);
+    public void setCompassTarget(@NotNull Location loc);
 
     /**
      * Get the previously set compass target.
      *
      * @return location of the target
      */
+    @NotNull
     public Location getCompassTarget();
 
     /**
@@ -125,6 +131,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @return the player's address
      */
+    @Nullable
     public InetSocketAddress getAddress();
 
     /**
@@ -132,21 +139,21 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @param message Message to be displayed
      */
-    public void sendRawMessage(String message);
+    public void sendRawMessage(@NotNull String message);
 
     /**
      * Kicks player with custom kick message.
      *
      * @param message kick message
      */
-    public void kickPlayer(String message);
+    public void kickPlayer(@Nullable String message);
 
     /**
      * Says a message (or runs a command).
      *
      * @param msg message to print
      */
-    public void chat(String msg);
+    public void chat(@NotNull String msg);
 
     /**
      * Makes the player perform the given command
@@ -154,7 +161,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param command Command to perform
      * @return true if the command was successful, otherwise false
      */
-    public boolean performCommand(String command);
+    public boolean performCommand(@NotNull String command);
 
     /**
      * Returns if the player is in sneak mode
@@ -229,7 +236,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated Magic value
      */
     @Deprecated
-    public void playNote(Location loc, byte instrument, byte note);
+    public void playNote(@NotNull Location loc, byte instrument, byte note);
 
     /**
      * Play a note for a player at a location. This requires a note block
@@ -240,7 +247,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param instrument The instrument
      * @param note The note
      */
-    public void playNote(Location loc, Instrument instrument, Note note);
+    public void playNote(@NotNull Location loc, @NotNull Instrument instrument, @NotNull Note note);
 
 
     /**
@@ -253,7 +260,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param volume The volume of the sound
      * @param pitch The pitch of the sound
      */
-    public void playSound(Location location, Sound sound, float volume, float pitch);
+    public void playSound(@NotNull Location location, @NotNull Sound sound, float volume, float pitch);
 
     /**
      * Play a sound for a player at the location.
@@ -267,7 +274,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param volume the volume of the sound
      * @param pitch the pitch of the sound
      */
-    public void playSound(Location location, String sound, float volume, float pitch);
+    public void playSound(@NotNull Location location, @NotNull String sound, float volume, float pitch);
 
     /**
      * Play a sound for a player at the location.
@@ -280,7 +287,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param volume The volume of the sound
      * @param pitch The pitch of the sound
      */
-    public void playSound(Location location, Sound sound, SoundCategory category, float volume, float pitch);
+    public void playSound(@NotNull Location location, @NotNull Sound sound, @NotNull SoundCategory category, float volume, float pitch);
 
     /**
      * Play a sound for a player at the location.
@@ -295,21 +302,21 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param volume the volume of the sound
      * @param pitch the pitch of the sound
      */
-    public void playSound(Location location, String sound, SoundCategory category, float volume, float pitch);
+    public void playSound(@NotNull Location location, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch);
 
     /**
      * Stop the specified sound from playing.
      *
      * @param sound the sound to stop
      */
-    public void stopSound(Sound sound);
+    public void stopSound(@NotNull Sound sound);
 
     /**
      * Stop the specified sound from playing.
      *
      * @param sound the sound to stop
      */
-    public void stopSound(String sound);
+    public void stopSound(@NotNull String sound);
 
     /**
      * Stop the specified sound from playing.
@@ -317,7 +324,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param sound the sound to stop
      * @param category the category of the sound
      */
-    public void stopSound(Sound sound, SoundCategory category);
+    public void stopSound(@NotNull Sound sound, @Nullable SoundCategory category);
 
     /**
      * Stop the specified sound from playing.
@@ -325,7 +332,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param sound the sound to stop
      * @param category the category of the sound
      */
-    public void stopSound(String sound, SoundCategory category);
+    public void stopSound(@NotNull String sound, @Nullable SoundCategory category);
 
     /**
      * Plays an effect to just this player.
@@ -336,7 +343,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated Magic value
      */
     @Deprecated
-    public void playEffect(Location loc, Effect effect, int data);
+    public void playEffect(@NotNull Location loc, @NotNull Effect effect, int data);
 
     /**
      * Plays an effect to just this player.
@@ -346,7 +353,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param effect the {@link Effect}
      * @param data a data bit needed for some effects
      */
-    public <T> void playEffect(Location loc, Effect effect, T data);
+    public <T> void playEffect(@NotNull Location loc, @NotNull Effect effect, @Nullable T data);
 
     /**
      * Send a block change. This fakes a block change packet for a user at a
@@ -358,7 +365,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated Magic value
      */
     @Deprecated
-    public void sendBlockChange(Location loc, Material material, byte data);
+    public void sendBlockChange(@NotNull Location loc, @NotNull Material material, byte data);
 
     /**
      * Send a block change. This fakes a block change packet for a user at a
@@ -367,7 +374,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param loc The location of the changed block
      * @param block The new block
      */
-    public void sendBlockChange(Location loc, BlockData block);
+    public void sendBlockChange(@NotNull Location loc, @NotNull BlockData block);
 
     /**
      * Send a chunk change. This fakes a chunk change packet for a user at a
@@ -387,7 +394,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated Magic value
      */
     @Deprecated
-    public boolean sendChunkChange(Location loc, int sx, int sy, int sz, byte[] data);
+    public boolean sendChunkChange(@NotNull Location loc, int sx, int sy, int sz, @NotNull byte[] data);
 
     /**
      * Send a sign change. This fakes a sign change packet for a user at
@@ -404,7 +411,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if location is null
      * @throws IllegalArgumentException if lines is non-null and has a length less than 4
      */
-    public void sendSignChange(Location loc, String[] lines) throws IllegalArgumentException;
+    public void sendSignChange(@NotNull Location loc, @Nullable String[] lines) throws IllegalArgumentException;
 
     /**
      * Render a map and send it to the player in its entirety. This may be
@@ -412,7 +419,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @param map The map to be sent
      */
-    public void sendMap(MapView map);
+    public void sendMap(@NotNull MapView map);
 
     /**
      * Forces an update of the player's entire inventory.
@@ -432,7 +439,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated future versions of Minecraft do not have achievements
      */
     @Deprecated
-    public void awardAchievement(Achievement achievement);
+    public void awardAchievement(@NotNull Achievement achievement);
 
     /**
      * Removes the given achievement and any children achievements that the
@@ -443,7 +450,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated future versions of Minecraft do not have achievements
      */
     @Deprecated
-    public void removeAchievement(Achievement achievement);
+    public void removeAchievement(@NotNull Achievement achievement);
 
     /**
      * Gets whether this player has the given achievement.
@@ -454,7 +461,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated future versions of Minecraft do not have achievements
      */
     @Deprecated
-    public boolean hasAchievement(Achievement achievement);
+    public boolean hasAchievement(@NotNull Achievement achievement);
 
     /**
      * Increments the given statistic for this player.
@@ -467,7 +474,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void incrementStatistic(Statistic statistic) throws IllegalArgumentException;
+    public void incrementStatistic(@NotNull Statistic statistic) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player.
@@ -480,7 +487,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void decrementStatistic(Statistic statistic) throws IllegalArgumentException;
+    public void decrementStatistic(@NotNull Statistic statistic) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player.
@@ -492,7 +499,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void incrementStatistic(Statistic statistic, int amount) throws IllegalArgumentException;
+    public void incrementStatistic(@NotNull Statistic statistic, int amount) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player.
@@ -504,7 +511,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void decrementStatistic(Statistic statistic, int amount) throws IllegalArgumentException;
+    public void decrementStatistic(@NotNull Statistic statistic, int amount) throws IllegalArgumentException;
 
     /**
      * Sets the given statistic for this player.
@@ -516,7 +523,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void setStatistic(Statistic statistic, int newValue) throws IllegalArgumentException;
+    public void setStatistic(@NotNull Statistic statistic, int newValue) throws IllegalArgumentException;
 
     /**
      * Gets the value of the given statistic for this player.
@@ -527,7 +534,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public int getStatistic(Statistic statistic) throws IllegalArgumentException;
+    public int getStatistic(@NotNull Statistic statistic) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player for the given material.
@@ -542,7 +549,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void incrementStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
+    public void incrementStatistic(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player for the given material.
@@ -557,7 +564,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void decrementStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
+    public void decrementStatistic(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException;
 
     /**
      * Gets the value of the given statistic for this player.
@@ -570,7 +577,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public int getStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
+    public int getStatistic(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player for the given material.
@@ -584,7 +591,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void incrementStatistic(Statistic statistic, Material material, int amount) throws IllegalArgumentException;
+    public void incrementStatistic(@NotNull Statistic statistic, @NotNull Material material, int amount) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player for the given material.
@@ -598,7 +605,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void decrementStatistic(Statistic statistic, Material material, int amount) throws IllegalArgumentException;
+    public void decrementStatistic(@NotNull Statistic statistic, @NotNull Material material, int amount) throws IllegalArgumentException;
 
     /**
      * Sets the given statistic for this player for the given material.
@@ -612,7 +619,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void setStatistic(Statistic statistic, Material material, int newValue) throws IllegalArgumentException;
+    public void setStatistic(@NotNull Statistic statistic, @NotNull Material material, int newValue) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player for the given entity.
@@ -627,7 +634,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void incrementStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
+    public void incrementStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player for the given entity.
@@ -642,7 +649,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void decrementStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
+    public void decrementStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType) throws IllegalArgumentException;
 
     /**
      * Gets the value of the given statistic for this player.
@@ -655,7 +662,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public int getStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
+    public int getStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player for the given entity.
@@ -669,7 +676,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void incrementStatistic(Statistic statistic, EntityType entityType, int amount) throws IllegalArgumentException;
+    public void incrementStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType, int amount) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player for the given entity.
@@ -683,7 +690,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void decrementStatistic(Statistic statistic, EntityType entityType, int amount);
+    public void decrementStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType, int amount);
 
     /**
      * Sets the given statistic for this player for the given entity.
@@ -697,7 +704,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void setStatistic(Statistic statistic, EntityType entityType, int newValue);
+    public void setStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType, int newValue);
 
     /**
      * Sets the current time on the player's client. When relative is true the
@@ -755,7 +762,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @param type The WeatherType enum type the player should experience
      */
-    public void setPlayerWeather(WeatherType type);
+    public void setPlayerWeather(@NotNull WeatherType type);
 
     /**
      * Returns the type of weather the player is currently experiencing.
@@ -763,6 +770,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @return The WeatherType that the player is currently experiencing or
      *     null if player is seeing server weather.
      */
+    @Nullable
     public WeatherType getPlayerWeather();
 
     /**
@@ -910,7 +918,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated see {@link #hidePlayer(Plugin, Player)}
      */
     @Deprecated
-    public void hidePlayer(Player player);
+    public void hidePlayer(@NotNull Player player);
 
     /**
      * Hides a player from this player
@@ -918,7 +926,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param plugin Plugin that wants to hide the player
      * @param player Player to hide
      */
-    public void hidePlayer(Plugin plugin, Player player);
+    public void hidePlayer(@NotNull Plugin plugin, @NotNull Player player);
 
     /**
      * Allows this player to see a player that was previously hidden
@@ -927,7 +935,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated see {@link #showPlayer(Plugin, Player)}
      */
     @Deprecated
-    public void showPlayer(Player player);
+    public void showPlayer(@NotNull Player player);
 
     /**
      * Allows this player to see a player that was previously hidden. If
@@ -937,7 +945,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param plugin Plugin that wants to show the player
      * @param player Player to show
      */
-    public void showPlayer(Plugin plugin, Player player);
+    public void showPlayer(@NotNull Plugin plugin, @NotNull Player player);
 
     /**
      * Checks to see if a player has been hidden from this player
@@ -946,7 +954,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @return True if the provided player is not being hidden from this
      *     player
      */
-    public boolean canSee(Player player);
+    public boolean canSee(@NotNull Player player);
 
     /**
      * Checks to see if this player is currently flying or not.
@@ -1030,7 +1038,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *     should use {@link #setResourcePack(String)}.
      */
     @Deprecated
-    public void setTexturePack(String url);
+    public void setTexturePack(@NotNull String url);
 
     /**
      * Request that the player's client download and switch resource packs.
@@ -1064,7 +1072,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException Thrown if the URL is too long. The
      *     length restriction is an implementation specific arbitrary value.
      */
-    public void setResourcePack(String url);
+    public void setResourcePack(@NotNull String url);
 
     /**
      * Request that the player's client download and switch resource packs.
@@ -1101,13 +1109,14 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException Thrown if the hash is not 20 bytes
      *     long.
      */
-    public void setResourcePack(String url, byte[] hash);
+    public void setResourcePack(@NotNull String url, @NotNull byte[] hash);
 
     /**
      * Gets the Scoreboard displayed to this player
      *
      * @return The current scoreboard seen by this player
      */
+    @NotNull
     public Scoreboard getScoreboard();
 
     /**
@@ -1120,7 +1129,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalStateException if this is a player that is not logged
      *     yet or has logged out
      */
-    public void setScoreboard(Scoreboard scoreboard) throws IllegalArgumentException, IllegalStateException;
+    public void setScoreboard(@NotNull Scoreboard scoreboard) throws IllegalArgumentException, IllegalStateException;
 
     /**
      * Gets if the client is displayed a 'scaled' health, that is, health on a
@@ -1173,6 +1182,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @return the followed entity, or null if not in spectator mode or not
      * following a specific entity.
      */
+    @Nullable
     public Entity getSpectatorTarget();
 
     /**
@@ -1183,7 +1193,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalStateException if the player is not in
      * {@link GameMode#SPECTATOR}
      */
-    public void setSpectatorTarget(Entity entity);
+    public void setSpectatorTarget(@Nullable Entity entity);
 
     /**
      * Sends a title and a subtitle message to the player. If either of these
@@ -1197,7 +1207,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated API behavior subject to change
      */
     @Deprecated
-    public void sendTitle(String title, String subtitle);
+    public void sendTitle(@Nullable String title, @Nullable String subtitle);
 
     /**
      * Sends a title and a subtitle message to the player. If either of these
@@ -1214,7 +1224,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param stay time in ticks for titles to stay. Defaults to 70.
      * @param fadeOut time in ticks for titles to fade out. Defaults to 20.
      */
-    public void sendTitle(String title, String subtitle, int fadeIn, int stay, int fadeOut);
+    public void sendTitle(@Nullable String title, @Nullable String subtitle, int fadeIn, int stay, int fadeOut);
 
     /**
      * Resets the title displayed to the player. This will clear the displayed
@@ -1230,7 +1240,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param location the location to spawn at
      * @param count the number of particles
      */
-    public void spawnParticle(Particle particle, Location location, int count);
+    public void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1242,7 +1252,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param z the position on the z axis to spawn at
      * @param count the number of particles
      */
-    public void spawnParticle(Particle particle, double x, double y, double z, int count);
+    public void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1254,7 +1264,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
      */
-    public <T> void spawnParticle(Particle particle, Location location, int count, T data);
+    public <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, @Nullable T data);
 
 
     /**
@@ -1269,7 +1279,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
      */
-    public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, T data);
+    public <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, @Nullable T data);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1284,7 +1294,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param offsetY the maximum random offset on the Y axis
      * @param offsetZ the maximum random offset on the Z axis
      */
-    public void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ);
+    public void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1301,7 +1311,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param offsetY the maximum random offset on the Y axis
      * @param offsetZ the maximum random offset on the Z axis
      */
-    public void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ);
+    public void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1318,7 +1328,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
      */
-    public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, T data);
+    public <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, @Nullable T data);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1337,7 +1347,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
      */
-    public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, T data);
+    public <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, @Nullable T data);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1354,7 +1364,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param extra the extra data for this particle, depends on the
      *              particle used (normally speed)
      */
-    public void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra);
+    public void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, double extra);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1373,7 +1383,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param extra the extra data for this particle, depends on the
      *              particle used (normally speed)
      */
-    public void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra);
+    public void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1392,7 +1402,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
      */
-    public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
+    public <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data);
 
     /**
      * Spawns the particle (the number of times specified by count)
@@ -1413,7 +1423,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
      */
-    public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
+    public <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data);
 
     /**
      * Return the player's progression on the specified advancement.
@@ -1421,7 +1431,8 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param advancement advancement
      * @return object detailing the player's progress
      */
-    public AdvancementProgress getAdvancementProgress(Advancement advancement);
+    @NotNull
+    public AdvancementProgress getAdvancementProgress(@NotNull Advancement advancement);
 
     /**
      * Get the player's current client side view distance.
@@ -1444,6 +1455,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * @return the player's locale
      */
+    @NotNull
     public String getLocale();
 
     /**

paper-api/src/main/java/org/bukkit/entity/Projectile.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.projectiles.ProjectileSource;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a shootable entity.
@@ -12,6 +13,7 @@ public interface Projectile extends Entity {
      *
      * @return the {@link ProjectileSource} that shot this projectile
      */
+    @Nullable
     public ProjectileSource getShooter();
 
     /**
@@ -19,7 +21,7 @@ public interface Projectile extends Entity {
      *
      * @param source the {@link ProjectileSource} that shot this projectile
      */
-    public void setShooter(ProjectileSource source);
+    public void setShooter(@Nullable ProjectileSource source);
 
     /**
      * Determine if this projectile should bounce or not when it hits.

paper-api/src/main/java/org/bukkit/entity/Rabbit.java

@@ -1,16 +1,19 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+
 public interface Rabbit extends Animals {
 
     /**
      * @return The type of rabbit.
      */
+    @NotNull
     public Type getRabbitType();
 
     /**
      * @param type Sets the type of rabbit for this entity.
      */
-    public void setRabbitType(Type type);
+    public void setRabbitType(@NotNull Type type);
 
     /**
      * Represents the various types a Rabbit might be.

paper-api/src/main/java/org/bukkit/entity/ShulkerBullet.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.Nullable;
+
 public interface ShulkerBullet extends Projectile {
 
     /**
@@ -7,6 +9,7 @@ public interface ShulkerBullet extends Projectile {
      *
      * @return the targeted entity
      */
+    @Nullable
     Entity getTarget();
 
     /**
@@ -14,5 +17,5 @@ public interface ShulkerBullet extends Projectile {
      *
      * @param target the entity to target
      */
-    void setTarget(Entity target);
+    void setTarget(@Nullable Entity target);
 }

paper-api/src/main/java/org/bukkit/entity/Skeleton.java

@@ -1,5 +1,8 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Represents a Skeleton.
  */
@@ -12,12 +15,14 @@ public interface Skeleton extends Monster {
      * @deprecated should check what class instance this is
      */
     @Deprecated
+    @NotNull
     public SkeletonType getSkeletonType();
 
     /**
      * @deprecated Must spawn a new subtype variant
      */
     @Deprecated
+    @Contract("_ -> fail")
     public void setSkeletonType(SkeletonType type);
 
     /*

paper-api/src/main/java/org/bukkit/entity/Spellcaster.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * Represents a spell casting "Illager".
  */
@@ -41,6 +43,7 @@ public interface Spellcaster extends Illager {
      *
      * @return the current spell
      */
+    @NotNull
     Spell getSpell();
 
     /**
@@ -48,5 +51,5 @@ public interface Spellcaster extends Illager {
      *
      * @param spell the spell the entity should be using
      */
-    void setSpell(Spell spell);
+    void setSpell(@NotNull Spell spell);
 }

paper-api/src/main/java/org/bukkit/entity/TNTPrimed.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.Location;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a Primed TNT.
@@ -36,5 +37,6 @@ public interface TNTPrimed extends Explosive {
      *
      * @return the source of this primed TNT
      */
+    @Nullable
     public Entity getSource();
 }

paper-api/src/main/java/org/bukkit/entity/Tameable.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.Nullable;
+
 public interface Tameable extends Entity {
 
     /**
@@ -28,6 +30,7 @@ public interface Tameable extends Entity {
      *
      * @return the owning AnimalTamer, or null if not owned
      */
+    @Nullable
     public AnimalTamer getOwner();
 
     /**
@@ -39,6 +42,6 @@ public interface Tameable extends Entity {
      *
      * @param tamer the AnimalTamer who should own this
      */
-    public void setOwner(AnimalTamer tamer);
+    public void setOwner(@Nullable AnimalTamer tamer);
 
 }

paper-api/src/main/java/org/bukkit/entity/ThrownPotion.java

@@ -4,6 +4,7 @@ import java.util.Collection;
 
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.potion.PotionEffect;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a thrown potion bottle
@@ -15,6 +16,7 @@ public interface ThrownPotion extends Projectile {
      *
      * @return The potion effects
      */
+    @NotNull
     public Collection<PotionEffect> getEffects();
 
     /**
@@ -26,6 +28,7 @@ public interface ThrownPotion extends Projectile {
      *
      * @return A copy of the ItemStack for this thrown potion.
      */
+    @NotNull
     public ItemStack getItem();
 
     /**
@@ -37,5 +40,5 @@ public interface ThrownPotion extends Projectile {
      *
      * @param item New ItemStack
      */
-    public void setItem(ItemStack item);
+    public void setItem(@NotNull ItemStack item);
 }

paper-api/src/main/java/org/bukkit/entity/TippedArrow.java

@@ -6,6 +6,8 @@ import org.bukkit.Color;
 import org.bukkit.potion.PotionData;
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 public interface TippedArrow extends Arrow {
 
@@ -14,13 +16,14 @@ public interface TippedArrow extends Arrow {
      *
      * @param data PotionData to set the base potion state to
      */
-    void setBasePotionData(PotionData data);
+    void setBasePotionData(@NotNull PotionData data);
 
     /**
      * Returns the potion data about the base potion
      *
      * @return a PotionData object
      */
+    @NotNull
     PotionData getBasePotionData();
 
     /**
@@ -28,6 +31,7 @@ public interface TippedArrow extends Arrow {
      *
      * @return arrow color
      */
+    @NotNull
     Color getColor();
 
     /**
@@ -35,7 +39,7 @@ public interface TippedArrow extends Arrow {
      *
      * @param color arrow color
      */
-    void setColor(Color color);
+    void setColor(@NotNull Color color);
 
     /**
      * Checks for the presence of custom potion effects.
@@ -53,6 +57,7 @@ public interface TippedArrow extends Arrow {
      *
      * @return the immutable list of custom potion effects
      */
+    @NotNull
     List<PotionEffect> getCustomEffects();
 
     /**
@@ -63,7 +68,7 @@ public interface TippedArrow extends Arrow {
      * overwritten
      * @return true if the effect was added as a result of this call
      */
-    boolean addCustomEffect(PotionEffect effect, boolean overwrite);
+    boolean addCustomEffect(@NotNull PotionEffect effect, boolean overwrite);
 
     /**
      * Removes a custom potion effect from this arrow.
@@ -73,7 +78,7 @@ public interface TippedArrow extends Arrow {
      * @throws IllegalArgumentException if this operation would leave the Arrow
      * in a state with no Custom Effects and PotionType.UNCRAFTABLE
      */
-    boolean removeCustomEffect(PotionEffectType type);
+    boolean removeCustomEffect(@NotNull PotionEffectType type);
 
     /**
      * Checks for a specific custom potion effect type on this arrow.
@@ -81,7 +86,7 @@ public interface TippedArrow extends Arrow {
      * @param type the potion effect type to check for
      * @return true if the potion has this effect
      */
-    boolean hasCustomEffect(PotionEffectType type);
+    boolean hasCustomEffect(@Nullable PotionEffectType type);
 
     /**
      * Removes all custom potion effects from this arrow.

paper-api/src/main/java/org/bukkit/entity/TropicalFish.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.DyeColor;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Tropical fish.
@@ -12,6 +13,7 @@ public interface TropicalFish extends Fish {
      *
      * @return pattern color
      */
+    @NotNull
     DyeColor getPatternColor();
 
     /**
@@ -19,13 +21,14 @@ public interface TropicalFish extends Fish {
      *
      * @param color pattern color
      */
-    void setPatternColor(DyeColor color);
+    void setPatternColor(@NotNull DyeColor color);
 
     /**
      * Gets the color of the fish's body.
      *
      * @return pattern color
      */
+    @NotNull
     DyeColor getBodyColor();
 
     /**
@@ -33,13 +36,14 @@ public interface TropicalFish extends Fish {
      *
      * @param color body color
      */
-    void setBodyColor(DyeColor color);
+    void setBodyColor(@NotNull DyeColor color);
 
     /**
      * Gets the fish's pattern.
      *
      * @return pattern
      */
+    @NotNull
     Pattern getPattern();
 
     /**
@@ -47,7 +51,7 @@ public interface TropicalFish extends Fish {
      *
      * @param pattern new pattern
      */
-    void setPattern(Pattern pattern);
+    void setPattern(@NotNull Pattern pattern);
 
     /**
      * Enumeration of all different fish patterns. Refer to the

paper-api/src/main/java/org/bukkit/entity/Vehicle.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.util.Vector;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a vehicle entity.
@@ -12,6 +13,7 @@ public interface Vehicle extends Entity {
      *
      * @return velocity vector
      */
+    @NotNull
     public Vector getVelocity();
 
     /**
@@ -19,5 +21,5 @@ public interface Vehicle extends Entity {
      *
      * @param vel velocity vector
      */
-    public void setVelocity(Vector vel);
+    public void setVelocity(@NotNull Vector vel);
 }

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

@@ -7,6 +7,8 @@ import java.util.List;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.Merchant;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a villager NPC
@@ -18,6 +20,7 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
      *
      * @return Current profession.
      */
+    @NotNull
     public Profession getProfession();
 
     /**
@@ -25,13 +28,14 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
      *
      * @param profession New profession.
      */
-    public void setProfession(Profession profession);
+    public void setProfession(@NotNull Profession profession);
 
     /**
      * Get the current {@link Career} for this Villager.
      *
      * @return the {@link Career}
      */
+    @NotNull
     public Career getCareer();
 
     /**
@@ -42,7 +46,7 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
      * @throws IllegalArgumentException when the new {@link Career} cannot be
      * used with this Villager's current {@link Profession}.
      */
-    public void setCareer(Career career);
+    public void setCareer(@Nullable Career career);
 
     /**
      * Set the new {@link Career} for this Villager.
@@ -53,7 +57,7 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
      * @throws IllegalArgumentException when the new {@link Career} cannot be
      * used with this Villager's current {@link Profession}.
      */
-    public void setCareer(Career career, boolean resetTrades);
+    public void setCareer(@Nullable Career career, boolean resetTrades);
 
     /**
      * Gets this villager's inventory.
@@ -63,6 +67,7 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
      *
      * {@inheritDoc}
      */
+    @NotNull
     @Override
     Inventory getInventory();
 
@@ -147,6 +152,7 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
          * @return an immutable list of careers for this profession, or an empty
          * map if this Profession has no careers.
          */
+        @NotNull
         public List<Career> getCareers() {
             return Career.getCareers(this);
         }
@@ -230,7 +236,7 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
         private static final Multimap<Profession, Career> careerMap = LinkedListMultimap.create();
         private final Profession profession;
 
-        private Career(Profession profession) {
+        private Career(@NotNull Profession profession) {
             this.profession = profession;
         }
 
@@ -239,6 +245,7 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
          *
          * @return the {@link Profession}.
          */
+        @NotNull
         public Profession getProfession() {
             return profession;
         }
@@ -251,7 +258,8 @@ public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
          * @return an immutable list of Careers that can be used by a
          * profession, or an empty map if the profession was not found
          */
-        public static List<Career> getCareers(Profession profession) {
+        @NotNull
+        public static List<Career> getCareers(@NotNull Profession profession) {
             return careerMap.containsKey(profession) ? ImmutableList.copyOf(careerMap.get(profession)) : ImmutableList.<Career>of();
         }
 

paper-api/src/main/java/org/bukkit/entity/Wolf.java

@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 import org.bukkit.DyeColor;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a Wolf
@@ -31,6 +32,7 @@ public interface Wolf extends Animals, Tameable, Sittable {
      *
      * @return the color of the collar
      */
+    @NotNull
     public DyeColor getCollarColor();
 
     /**
@@ -38,5 +40,5 @@ public interface Wolf extends Animals, Tameable, Sittable {
      *
      * @param color the color to apply
      */
-    public void setCollarColor(DyeColor color);
+    public void setCollarColor(@NotNull DyeColor color);
 }

paper-api/src/main/java/org/bukkit/entity/Zombie.java

@@ -1,5 +1,8 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Nullable;
+
 /**
  * Represents a Zombie.
  */
@@ -33,6 +36,7 @@ public interface Zombie extends Monster {
      * @deprecated must spawn {@link ZombieVillager}.
      */
     @Deprecated
+    @Contract("_ -> fail")
     public void setVillager(boolean flag);
 
     /**
@@ -40,6 +44,7 @@ public interface Zombie extends Monster {
      * @see ZombieVillager#getVillagerProfession()
      */
     @Deprecated
+    @Contract("_ -> fail")
     public void setVillagerProfession(Villager.Profession profession);
 
     /**
@@ -47,6 +52,8 @@ public interface Zombie extends Monster {
      * @see ZombieVillager#getVillagerProfession()
      */
     @Deprecated
+    @Nullable
+    @Contract("-> null")
     public Villager.Profession getVillagerProfession();
 
     /**

paper-api/src/main/java/org/bukkit/entity/ZombieVillager.java

@@ -1,5 +1,7 @@
 package org.bukkit.entity;
 
+import org.jetbrains.annotations.Nullable;
+
 /**
  * Represents a {@link Zombie} which was once a {@link Villager}.
  */
@@ -9,7 +11,7 @@ public interface ZombieVillager extends Zombie {
      * Sets the villager profession of this zombie.
      */
     @Override
-    void setVillagerProfession(Villager.Profession profession);
+    void setVillagerProfession(@Nullable Villager.Profession profession);
 
     /**
      * Returns the villager profession of this zombie.
@@ -17,6 +19,7 @@ public interface ZombieVillager extends Zombie {
      * @return the profession or null
      */
     @Override
+    @Nullable
     Villager.Profession getVillagerProfession();
 
     /**

paper-api/src/main/java/org/bukkit/entity/minecart/CommandMinecart.java

@@ -1,6 +1,8 @@
 package org.bukkit.entity.minecart;
 
 import org.bukkit.entity.Minecart;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 public interface CommandMinecart extends Minecart {
 
@@ -11,6 +13,7 @@ public interface CommandMinecart extends Minecart {
      *
      * @return Command that this CommandMinecart will run when powered.
      */
+    @NotNull
     public String getCommand();
 
     /**
@@ -21,7 +24,7 @@ public interface CommandMinecart extends Minecart {
      * @param command Command that this CommandMinecart will run when
      *     activated.
      */
-    public void setCommand(String command);
+    public void setCommand(@Nullable String command);
 
     /**
      * Sets the name of this CommandMinecart.  The name is used with commands
@@ -30,6 +33,6 @@ public interface CommandMinecart extends Minecart {
      *
      * @param name New name for this CommandMinecart.
      */
-    public void setName(String name);
+    public void setName(@Nullable String name);
 
 }