* This currently only returns bossbars shown to the player via * {@link #showBossBar(net.kyori.adventure.bossbar.BossBar)} and does not contain bukkit * {@link org.bukkit.boss.BossBar} instances shown to the player. * * @return an unmodifiable view of all known currently active bossbars * @since 4.14.0 */ @Override @org.jetbrains.annotations.UnmodifiableView @NotNull Iterable activeBossBars(); /** * Gets the "friendly" name to display of this player. * * @return the display name */ net.kyori.adventure.text.@NotNull Component displayName(); /** * Sets the "friendly" name to display of this player. * * @param displayName the display name to set */ void displayName(final net.kyori.adventure.text.@Nullable Component displayName); // Paper end /** * {@inheritDoc} */ @NotNull @Override public String getName(); /** * Gets the "friendly" name to display of this player. This may include * color. *
* Note that this name will not be displayed in game, only in chat and * places defined by plugins. * * @return the friendly name * @deprecated in favour of {@link #displayName()} */ @Deprecated // Paper @NotNull public String getDisplayName(); /** * Sets the "friendly" name to display of this player. This may include * color. *
* Note that this name will not be displayed in game, only in chat and * places defined by plugins. * * @param name The new display name. * @deprecated in favour of {@link #displayName(net.kyori.adventure.text.Component)} */ @Deprecated // Paper public void setDisplayName(@Nullable String name); // Paper start /** * Sets the name that is shown on the in-game player list. *
* If the value is null, the name will be identical to {@link #getName()}. * * @param name new player list name */ void playerListName(net.kyori.adventure.text.@Nullable Component name); /** * Gets the name that is shown on the in-game player list. * * @return the player list name */ net.kyori.adventure.text.@NotNull Component playerListName(); /** * Gets the currently displayed player list header for this player. * * @return player list header or null */ net.kyori.adventure.text.@Nullable Component playerListHeader(); /** * Gets the currently displayed player list footer for this player. * * @return player list footer or null */ net.kyori.adventure.text.@Nullable Component playerListFooter(); // Paper end /** * Gets the name that is shown on the player list. * * @return the player list name * @deprecated in favour of {@link #playerListName()} */ @NotNull @Deprecated // Paper public String getPlayerListName(); /** * Sets the name that is shown on the in-game player list. *
* If the value is null, the name will be identical to {@link #getName()}.
*
* @param name new player list name
* @deprecated in favour of {@link #playerListName(net.kyori.adventure.text.Component)}
*/
@Deprecated // Paper
public void setPlayerListName(@Nullable String name);
/**
* Gets the relative order that the player is shown on the player list.
*
* @return the player list order
*/
public int getPlayerListOrder();
/**
* Sets the relative order that the player is shown on the in-game player
* list.
*
* @param order new player list order, must be positive
*/
public void setPlayerListOrder(int order);
/**
* Gets the currently displayed player list header for this player.
*
* @return player list header or null
* @deprecated in favour of {@link #playerListHeader()}
*/
@Deprecated // Paper
@Nullable
public String getPlayerListHeader();
/**
* Gets the currently displayed player list footer for this player.
*
* @return player list header or null
* @deprecated in favour of {@link #playerListFooter()}
*/
@Deprecated // Paper
@Nullable
public String getPlayerListFooter();
/**
* Sets the currently displayed player list header for this player.
*
* @param header player list header, null for empty
* @deprecated in favour of {@link #sendPlayerListHeader(net.kyori.adventure.text.Component)}
*/
@Deprecated // Paper
public void setPlayerListHeader(@Nullable String header);
/**
* Sets the currently displayed player list footer for this player.
*
* @param footer player list footer, null for empty
* @deprecated in favour of {@link #sendPlayerListFooter(net.kyori.adventure.text.Component)}
*/
@Deprecated // Paper
public void setPlayerListFooter(@Nullable String footer);
/**
* Sets the currently displayed player list header and footer for this
* player.
*
* @param header player list header, null for empty
* @param footer player list footer, null for empty
* @deprecated in favour of {@link #sendPlayerListHeaderAndFooter(net.kyori.adventure.text.Component, net.kyori.adventure.text.Component)}
*/
@Deprecated // Paper
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(@NotNull Location loc);
/**
* Get the previously set compass target.
*
* @return location of the target
*/
@NotNull
public Location getCompassTarget();
/**
* Gets the socket address of this player
*
* @return the player's address
*/
@Nullable
public InetSocketAddress getAddress();
/**
* Gets if this connection has been transferred from another server.
*
* @return true if the connection has been transferred
*/
public boolean isTransferred();
/**
* Retrieves a cookie from this player.
*
* @param key the key identifying the cookie cookie
* @return a {@link CompletableFuture} that will be completed when the
* Cookie response is received or otherwise available. If the cookie is not
* set in the client, the {@link CompletableFuture} will complete with a
* null value.
*/
@NotNull
CompletableFuture
* Note: This will overwrite the players current inventory, health,
* motion, etc, with the state from the saved dat file.
*/
public void loadData();
/**
* Sets whether the player is ignored as not sleeping. If everyone is
* either sleeping or has this flag set, then time will advance to the
* next day. If everyone has this flag set but no one is actually in bed,
* then nothing will happen.
*
* @param isSleeping Whether to ignore.
*/
public void setSleepingIgnored(boolean isSleeping);
/**
* Returns whether the player is sleeping ignored.
*
* @return Whether player is ignoring sleep.
*/
public boolean isSleepingIgnored();
/**
* Gets the Location where the player will spawn at their bed, null if
* they have not slept in one or their current bed spawn is invalid.
*
* @return Bed Spawn Location if bed exists, otherwise null.
*
* @see #getRespawnLocation()
* @deprecated Misleading name. This method also returns the location of
* respawn anchors.
*/
@Nullable
@Override
@Deprecated(since = "1.20.4")
public Location getBedSpawnLocation();
/**
* Gets the Location where the player will spawn at, null if they
* don't have a valid respawn point.
*
* @return respawn location if exists, otherwise null.
*/
@Nullable
@Override
public Location getRespawnLocation();
/**
* Sets the Location where the player will spawn at their bed.
*
* @param location where to set the respawn location
*
* @see #setRespawnLocation(Location)
* @deprecated Misleading name. This method sets the player's respawn
* location more generally and is not limited to beds.
*/
@Deprecated(since = "1.20.4")
public void setBedSpawnLocation(@Nullable Location location);
/**
* Sets the Location where the player will respawn.
*
* @param location where to set the respawn location
*/
public void setRespawnLocation(@Nullable Location location);
/**
* Sets the Location where the player will spawn at their bed.
*
* @param location where to set the respawn location
* @param force whether to forcefully set the respawn location even if a
* valid bed is not present
*
* @see #setRespawnLocation(Location, boolean)
* @deprecated Misleading name. This method sets the player's respawn
* location more generally and is not limited to beds.
*/
@Deprecated(since = "1.20.4")
public void setBedSpawnLocation(@Nullable Location location, boolean force);
/**
* Sets the Location where the player will respawn.
*
* @param location where to set the respawn location
* @param force whether to forcefully set the respawn location even if a
* valid respawn point is not present
*/
public void setRespawnLocation(@Nullable Location location, boolean force);
/**
* Gets the ender pearls currently associated with this entity.
*
* The returned list will not be directly linked to the entity's current
* pearls, and no guarantees are made as to its mutability.
*
* @return collection of entities corresponding to current pearls.
*/
@NotNull
@ApiStatus.Experimental
public Collection
* This method will fail silently when called with {@link Instrument#CUSTOM_HEAD}.
* @param loc The location to play the note
* @param instrument The instrument
* @param note The note
*/
public void playNote(@NotNull Location loc, @NotNull Instrument instrument, @NotNull Note note);
/**
* Play a sound for a player at the location.
*
* This function will fail silently if Location or Sound are null.
*
* @param location The location to play the sound
* @param sound The sound to play
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
public void playSound(@NotNull Location location, @NotNull Sound sound, float volume, float pitch);
/**
* Play a sound for a player at the location.
*
* This function will fail silently if Location or Sound are null. No
* sound will be heard by the player if their client does not have the
* respective sound for the value passed.
*
* @param location The location to play the sound
* @param sound The internal sound name to play
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
public void playSound(@NotNull Location location, @NotNull String sound, float volume, float pitch);
/**
* Play a sound for a player at the location.
*
* This function will fail silently if Location or Sound are null.
*
* @param location The location to play the sound
* @param sound The sound to play
* @param category The category of the sound
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
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.
*
* This function will fail silently if Location or Sound are null. No sound
* will be heard by the player if their client does not have the respective
* sound for the value passed.
*
* @param location The location to play the sound
* @param sound The internal sound name to play
* @param category The category of the sound
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
public void playSound(@NotNull Location location, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch);
/**
* Play a sound for a player at the location. For sounds with multiple
* variations passing the same seed will always play the same variation.
*
* This function will fail silently if Location or Sound are null.
*
* @param location The location to play the sound
* @param sound The sound to play
* @param category The category of the sound
* @param volume The volume of the sound
* @param pitch The pitch of the sound
* @param seed The seed for the sound
*/
public void playSound(@NotNull Location location, @NotNull Sound sound, @NotNull SoundCategory category, float volume, float pitch, long seed);
/**
* Play a sound for a player at the location. For sounds with multiple
* variations passing the same seed will always play the same variation.
*
* This function will fail silently if Location or Sound are null. No sound
* will be heard by the player if their client does not have the respective
* sound for the value passed.
*
* @param location The location to play the sound
* @param sound The internal sound name to play
* @param category The category of the sound
* @param volume The volume of the sound
* @param pitch The pitch of the sound
* @param seed The seed for the sound
*/
public void playSound(@NotNull Location location, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch, long seed);
/**
* Play a sound for a player at the location of the entity.
*
* This function will fail silently if Entity or Sound are null.
*
* @param entity The entity to play the sound
* @param sound The sound to play
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
public void playSound(@NotNull Entity entity, @NotNull Sound sound, float volume, float pitch);
/**
* Play a sound for a player at the location of the entity.
*
* This function will fail silently if Entity or Sound are null.
*
* @param entity The entity to play the sound
* @param sound The sound to play
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
public void playSound(@NotNull Entity entity, @NotNull String sound, float volume, float pitch);
/**
* Play a sound for a player at the location of the entity.
*
* This function will fail silently if Entity or Sound are null.
*
* @param entity The entity to play the sound
* @param sound The sound to play
* @param category The category of the sound
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
public void playSound(@NotNull Entity entity, @NotNull Sound sound, @NotNull SoundCategory category, float volume, float pitch);
/**
* Play a sound for a player at the location of the entity.
*
* This function will fail silently if Entity or Sound are null.
*
* @param entity The entity to play the sound
* @param sound The sound to play
* @param category The category of the sound
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
public void playSound(@NotNull Entity entity, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch);
/**
* Play a sound for a player at the location of the entity. For sounds with
* multiple variations passing the same seed will always play the same variation.
*
* This function will fail silently if Entity or Sound are null.
*
* @param entity The entity to play the sound
* @param sound The sound to play
* @param category The category of the sound
* @param volume The volume of the sound
* @param pitch The pitch of the sound
* @param seed The seed for the sound
*/
public void playSound(@NotNull Entity entity, @NotNull Sound sound, @NotNull SoundCategory category, float volume, float pitch, long seed);
/**
* Play a sound for a player at the location of the entity. For sounds with
* multiple variations passing the same seed will always play the same variation.
*
* This function will fail silently if Entity or Sound are null.
*
* @param entity The entity to play the sound
* @param sound The sound to play
* @param category The category of the sound
* @param volume The volume of the sound
* @param pitch The pitch of the sound
* @param seed The seed for the sound
*/
public void playSound(@NotNull Entity entity, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch, long seed);
/**
* Stop the specified sound from playing.
*
* @param sound the sound to stop
*/
public void stopSound(@NotNull Sound sound);
/**
* Stop the specified sound from playing.
*
* @param sound the sound to stop
*/
public void stopSound(@NotNull String sound);
/**
* Stop the specified sound from playing.
*
* @param sound the sound to stop
* @param category the category of the sound
*/
public void stopSound(@NotNull Sound sound, @Nullable SoundCategory category);
/**
* Stop the specified sound from playing.
*
* @param sound the sound to stop
* @param category the category of the sound
*/
public void stopSound(@NotNull String sound, @Nullable SoundCategory category);
/**
* Stop the specified sound category from playing.
*
* @param category the sound category to stop
*/
public void stopSound(@NotNull SoundCategory category);
/**
* Stop all sounds from playing.
*/
public void stopAllSounds();
/**
* Plays an effect to just this player.
*
* @param loc the location to play the effect at
* @param effect the {@link Effect}
* @param data a data bit needed for some effects
* @deprecated Magic value
*/
@Deprecated(since = "1.6.2")
public void playEffect(@NotNull Location loc, @NotNull Effect effect, int data);
/**
* Plays an effect to just this player.
*
* @param
* Note that this method will call a {@link BlockBreakEvent}, meaning that
* this method may not be successful in breaking the block if the event was
* cancelled by a third party plugin. Care should be taken if running this
* method in a BlockBreakEvent listener as recursion may be possible if it
* is invoked on the same {@link Block} being broken in the event.
*
* Additionally, a {@link BlockDropItemEvent} is called for the items
* dropped by this method (if successful).
*
* The block must be in the same world as the player.
*
* @param block the block to break
*
* @return true if the block was broken, false if the break failed
*/
public boolean breakBlock(@NotNull Block block);
/**
* Send a block change. This fakes a block change packet for a user at a
* certain location. This will not actually change the world in any way.
*
* @param loc The location of the changed block
* @param material The new block
* @param data The block data
* @deprecated Magic value
*/
@Deprecated(since = "1.6.2")
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
* certain location. This will not actually change the world in any way.
*
* @param loc The location of the changed block
* @param block The new block
*/
public void sendBlockChange(@NotNull Location loc, @NotNull BlockData block);
/**
* Send a multi-block change. This fakes a block change packet for a user
* at multiple locations. This will not actually change the world in any
* way.
*
* This method may send multiple packets to the client depending on the
* blocks in the collection. A packet must be sent for each chunk section
* modified, meaning one packet for each 16x16x16 block area. Even if only
* one block is changed in two different chunk sections, two packets will
* be sent.
*
* Additionally, this method cannot guarantee the functionality of changes
* being sent to the player in chunks not loaded by the client. It is the
* responsibility of the caller to ensure that the client is within range
* of the changed blocks or to handle any side effects caused as a result.
*
* @param blocks the block states to send to the player
*/
public void sendBlockChanges(@NotNull Collection
* This method may send multiple packets to the client depending on the
* blocks in the collection. A packet must be sent for each chunk section
* modified, meaning one packet for each 16x16x16 block area. Even if only
* one block is changed in two different chunk sections, two packets will
* be sent.
*
* Additionally, this method cannot guarantee the functionality of changes
* being sent to the player in chunks not loaded by the client. It is the
* responsibility of the caller to ensure that the client is within range
* of the changed blocks or to handle any side effects caused as a result.
*
* @param blocks the block states to send to the player
* @param suppressLightUpdates whether or not light updates should be
* suppressed when updating the blocks on the client
* @deprecated suppressLightUpdates is not functional in versions greater
* than 1.19.4
*/
@Deprecated(since = "1.20")
public void sendBlockChanges(@NotNull Collection
* At the same location for each unique damage source sent to the player, a
* separate damage overlay will be displayed with the given progress. This allows
* for block damage at different progress from multiple entities at once.
*
* @param loc the location of the damaged block
* @param progress the progress from 0.0 - 1.0 where 0 is no damage and
* 1.0 is the most damaged
* @param source the entity to which the damage belongs
*/
public void sendBlockDamage(@NotNull Location loc, float progress, @NotNull Entity source);
/**
* Send block damage. This fakes block break progress at a certain location
* sourced by the provided entity id. This will not actually change the block's
* break progress in any way.
*
* At the same location for each unique damage source sent to the player, a
* separate damage overlay will be displayed with the given progress. This allows
* for block damage at different progress from multiple entities at once.
*
* @param loc the location of the damaged block
* @param progress the progress from 0.0 - 1.0 where 0 is no damage and
* 1.0 is the most damaged
* @param sourceId the entity id of the entity to which the damage belongs.
* Can be an id that does not associate directly with an existing or loaded entity.
*/
public void sendBlockDamage(@NotNull Location loc, float progress, int sourceId);
/**
* Send an equipment change for the target entity. This will not
* actually change the entity's equipment in any way.
*
* @param entity the entity whose equipment to change
* @param slot the slot to change
* @param item the item to which the slot should be changed, or null to set
* it to air
*/
public void sendEquipmentChange(@NotNull LivingEntity entity, @NotNull EquipmentSlot slot, @Nullable ItemStack item);
/**
* Send multiple equipment changes for the target entity. This will not
* actually change the entity's equipment in any way.
*
* @param entity the entity whose equipment to change
* @param items the slots to change, where the values are the items to which
* the slot should be changed. null values will set the slot to air
*/
public void sendEquipmentChange(@NotNull LivingEntity entity, @NotNull Map
* If the client does not have a sign at the given location it will
* display an error message to the user.
*
* @param loc the location of the sign
* @param lines the new text on the sign or null to clear it
* @throws IllegalArgumentException if location is null
* @throws IllegalArgumentException if lines is non-null and has a length less than 4
* @deprecated Use {@link #sendBlockUpdate(Location, TileState)} by creating a new virtual
* {@link org.bukkit.block.Sign} block state via {@link BlockData#createBlockState()}
* (constructed e.g. via {@link Material#createBlockData()})
*/
@Deprecated
default void sendSignChange(@NotNull Location loc, @Nullable java.util.List lines) throws IllegalArgumentException {
this.sendSignChange(loc, lines, DyeColor.BLACK);
}
/**
* Send a sign change. This fakes a sign change packet for a user at
* a certain location. This will not actually change the world in any way.
* This method will use a sign at the location's block or a faked sign
* sent via
* {@link #sendBlockChange(org.bukkit.Location, org.bukkit.Material, byte)}.
*
* If the client does not have a sign at the given location it will
* display an error message to the user.
*
* @param loc the location of the sign
* @param lines the new text on the sign or null to clear it
* @param dyeColor the color of the sign
* @throws IllegalArgumentException if location is null
* @throws IllegalArgumentException if dyeColor is null
* @throws IllegalArgumentException if lines is non-null and has a length less than 4
* @deprecated Use {@link #sendBlockUpdate(Location, TileState)} by creating a new virtual
* {@link org.bukkit.block.Sign} block state via {@link BlockData#createBlockState()}
* (constructed e.g. via {@link Material#createBlockData()})
*/
@Deprecated
default void sendSignChange(@NotNull Location loc, @Nullable java.util.List lines, @NotNull DyeColor dyeColor) throws IllegalArgumentException {
this.sendSignChange(loc, lines, dyeColor, false);
}
/**
* Send a sign change. This fakes a sign change packet for a user at
* a certain location. This will not actually change the world in any way.
* This method will use a sign at the location's block or a faked sign
* sent via
* {@link #sendBlockChange(org.bukkit.Location, org.bukkit.Material, byte)}.
*
* If the client does not have a sign at the given location it will
* display an error message to the user.
*
* @param loc the location of the sign
* @param lines the new text on the sign or null to clear it
* @param hasGlowingText whether the text of the sign should glow as if dyed with a glowing ink sac
* @throws IllegalArgumentException if location is null
* @throws IllegalArgumentException if dyeColor is null
* @throws IllegalArgumentException if lines is non-null and has a length less than 4
* @deprecated Use {@link #sendBlockUpdate(Location, TileState)} by creating a new virtual
* {@link org.bukkit.block.Sign} block state via {@link BlockData#createBlockState()}
* (constructed e.g. via {@link Material#createBlockData()})
*/
@Deprecated
default void sendSignChange(@NotNull Location loc, @Nullable java.util.List lines, boolean hasGlowingText) throws IllegalArgumentException {
this.sendSignChange(loc, lines, DyeColor.BLACK, hasGlowingText);
}
/**
* Send a sign change. This fakes a sign change packet for a user at
* a certain location. This will not actually change the world in any way.
* This method will use a sign at the location's block or a faked sign
* sent via
* {@link #sendBlockChange(org.bukkit.Location, org.bukkit.Material, byte)}.
*
* If the client does not have a sign at the given location it will
* display an error message to the user.
*
* @param loc the location of the sign
* @param lines the new text on the sign or null to clear it
* @param dyeColor the color of the sign
* @param hasGlowingText whether the text of the sign should glow as if dyed with a glowing ink sac
* @throws IllegalArgumentException if location is null
* @throws IllegalArgumentException if dyeColor is null
* @throws IllegalArgumentException if lines is non-null and has a length less than 4
* @deprecated Use {@link #sendBlockUpdate(Location, TileState)} by creating a new virtual
* {@link org.bukkit.block.Sign} block state via {@link BlockData#createBlockState()}
* (constructed e.g. via {@link Material#createBlockData()})
*/
@Deprecated
void sendSignChange(@NotNull Location loc, @Nullable java.util.List lines, @NotNull DyeColor dyeColor, boolean hasGlowingText)
throws IllegalArgumentException;
// Paper end
/**
* Send a sign change. This fakes a sign change packet for a user at
* a certain location. This will not actually change the world in any way.
* This method will use a sign at the location's block or a faked sign
* sent via
* {@link #sendBlockChange(org.bukkit.Location, org.bukkit.block.data.BlockData)}.
*
* If the client does not have a sign at the given location it will
* display an error message to the user.
*
* To change all attributes of a sign, including the back Side, use
* {@link #sendBlockUpdate(org.bukkit.Location, org.bukkit.block.TileState)}.
*
* @param loc the location of the sign
* @param lines the new text on the sign or null to clear it
* @throws IllegalArgumentException if location is null
* @throws IllegalArgumentException if lines is non-null and has a length less than 4
* @deprecated Use {@link #sendBlockUpdate(Location, TileState)} by creating a new virtual
* {@link org.bukkit.block.Sign} block state via {@link BlockData#createBlockState()}
* (constructed e.g. via {@link Material#createBlockData()})
*/
@Deprecated // Paper
public void sendSignChange(@NotNull Location loc, @Nullable String[] lines) throws IllegalArgumentException;
/**
* Send a sign change. This fakes a sign change packet for a user at
* a certain location. This will not actually change the world in any way.
* This method will use a sign at the location's block or a faked sign
* sent via
* {@link #sendBlockChange(org.bukkit.Location, org.bukkit.block.data.BlockData)}.
*
* If the client does not have a sign at the given location it will
* display an error message to the user.
*
* To change all attributes of a sign, including the back Side, use
* {@link #sendBlockUpdate(org.bukkit.Location, org.bukkit.block.TileState)}.
*
* @param loc the location of the sign
* @param lines the new text on the sign or null to clear it
* @param dyeColor the color of the sign
* @throws IllegalArgumentException if location is null
* @throws IllegalArgumentException if dyeColor is null
* @throws IllegalArgumentException if lines is non-null and has a length less than 4
* @deprecated Use {@link #sendBlockUpdate(Location, TileState)} by creating a new virtual
* {@link org.bukkit.block.Sign} block state via {@link BlockData#createBlockState()}
* (constructed e.g. via {@link Material#createBlockData()})
*/
@Deprecated // Paper
public void sendSignChange(@NotNull Location loc, @Nullable String[] lines, @NotNull DyeColor dyeColor) throws IllegalArgumentException;
/**
* Send a sign change. This fakes a sign change packet for a user at
* a certain location. This will not actually change the world in any way.
* This method will use a sign at the location's block or a faked sign
* sent via
* {@link #sendBlockChange(org.bukkit.Location, org.bukkit.block.data.BlockData)}.
*
* If the client does not have a sign at the given location it will
* display an error message to the user.
*
* To change all attributes of a sign, including the back Side, use
* {@link #sendBlockUpdate(org.bukkit.Location, org.bukkit.block.TileState)}.
*
* @param loc the location of the sign
* @param lines the new text on the sign or null to clear it
* @param dyeColor the color of the sign
* @param hasGlowingText if the sign's text should be glowing
* @throws IllegalArgumentException if location is null
* @throws IllegalArgumentException if dyeColor is null
* @throws IllegalArgumentException if lines is non-null and has a length less than 4
* @deprecated Use {@link #sendBlockUpdate(Location, TileState)} by creating a new virtual
* {@link org.bukkit.block.Sign} block state via {@link BlockData#createBlockState()}
* (constructed e.g. via {@link Material#createBlockData()})
*/
@Deprecated // Paper
public void sendSignChange(@NotNull Location loc, @Nullable String[] lines, @NotNull DyeColor dyeColor, boolean hasGlowingText) throws IllegalArgumentException;
/**
* Send a TileState change. This fakes a TileState change for a user at
* the given location. This will not actually change the world in any way.
* This method will use a TileState at the location's block or a faked TileState
* sent via
* {@link #sendBlockChange(org.bukkit.Location, org.bukkit.block.data.BlockData)}.
*
* If the client does not have an appropriate tile at the given location it
* may display an error message to the user.
*
* {@link BlockData#createBlockState()} can be used to create a {@link BlockState}.
*
* @param loc the location of the sign
* @param tileState the tile state
* @throws IllegalArgumentException if location is null
* @throws IllegalArgumentException if tileState is null
*/
@ApiStatus.Experimental
public void sendBlockUpdate(@NotNull Location loc, @NotNull TileState tileState) throws IllegalArgumentException;
/**
* Change a potion effect for the target entity. This will not actually
* change the entity's potion effects in any way.
*
* Note: Sending an effect change to a player for themselves may
* cause unexpected behavior on the client. Effects sent this way will also
* not be removed when their timer reaches 0, they can be removed with
* {@link #sendPotionEffectChangeRemove(LivingEntity, PotionEffectType)}
*
* @param entity the entity whose potion effects to change
* @param effect the effect to change
*/
public void sendPotionEffectChange(@NotNull LivingEntity entity, @NotNull PotionEffect effect);
/**
* Remove a potion effect for the target entity. This will not actually
* change the entity's potion effects in any way.
*
* Note: Sending an effect change to a player for themselves may
* cause unexpected behavior on the client.
*
* @param entity the entity whose potion effects to change
* @param type the effect type to remove
*/
public void sendPotionEffectChangeRemove(@NotNull LivingEntity entity, @NotNull PotionEffectType type);
/**
* Render a map and send it to the player in its entirety. This may be
* used when streaming the map in the normal manner is not desirable.
*
* @param map The map to be sent
*/
public void sendMap(@NotNull MapView map);
// Paper start
/**
* Sends an Action Bar message to the client.
*
* Use Section symbols for legacy color codes to send formatting.
*
* @param message The message to send
* @deprecated use {@link #sendActionBar(net.kyori.adventure.text.Component)}
*/
@Deprecated
public void sendActionBar(@NotNull String message);
/**
* Sends an Action Bar message to the client.
*
* Use supplied alternative character to the section symbol to represent legacy color codes.
*
* @param alternateChar Alternate symbol such as '&'
* @param message The message to send
* @deprecated use {@link #sendActionBar(net.kyori.adventure.text.Component)}
*/
@Deprecated
public void sendActionBar(char alternateChar, @NotNull String message);
/**
* Sends an Action Bar message to the client.
*
* @param message The components to send
* @deprecated use {@link #sendActionBar(net.kyori.adventure.text.Component)}
*/
@Deprecated
public void sendActionBar(@NotNull net.md_5.bungee.api.chat.BaseComponent... message);
/**
* Sends the component to the player
*
* @param component the components to send
* @deprecated use {@code sendMessage} methods that accept {@link net.kyori.adventure.text.Component}
*/
@Override
@Deprecated
public default void sendMessage(@NotNull net.md_5.bungee.api.chat.BaseComponent component) {
spigot().sendMessage(component);
}
/**
* Sends an array of components as a single message to the player
*
* @param components the components to send
* @deprecated use {@code sendMessage} methods that accept {@link net.kyori.adventure.text.Component}
*/
@Override
@Deprecated
public default void sendMessage(@NotNull net.md_5.bungee.api.chat.BaseComponent... components) {
spigot().sendMessage(components);
}
/**
* Sends an array of components as a single message to the specified screen position of this player
*
* @deprecated This is unlikely the API you want to use. See {@link #sendActionBar(String)} for a more proper Action Bar API. This deprecated API may send unsafe items to the client.
* @param position the screen position
* @param components the components to send
*/
@Deprecated
public default void sendMessage(net.md_5.bungee.api.ChatMessageType position, net.md_5.bungee.api.chat.BaseComponent... components) {
spigot().sendMessage(position, components);
}
/**
* Set the text displayed in the player list header and footer for this player
*
* @param header content for the top of the player list
* @param footer content for the bottom of the player list
* @deprecated in favour of {@link #sendPlayerListHeaderAndFooter(net.kyori.adventure.text.Component, net.kyori.adventure.text.Component)}
*/
@Deprecated
public void setPlayerListHeaderFooter(@Nullable net.md_5.bungee.api.chat.BaseComponent[] header, @Nullable net.md_5.bungee.api.chat.BaseComponent[] footer);
/**
* Set the text displayed in the player list header and footer for this player
*
* @param header content for the top of the player list
* @param footer content for the bottom of the player list
* @deprecated in favour of {@link #sendPlayerListHeaderAndFooter(net.kyori.adventure.text.Component, net.kyori.adventure.text.Component)}
*/
@Deprecated
public void setPlayerListHeaderFooter(@Nullable net.md_5.bungee.api.chat.BaseComponent header, @Nullable net.md_5.bungee.api.chat.BaseComponent footer);
/**
* Update the times for titles displayed to the player
*
* @param fadeInTicks ticks to fade-in
* @param stayTicks ticks to stay visible
* @param fadeOutTicks ticks to fade-out
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated
public void setTitleTimes(int fadeInTicks, int stayTicks, int fadeOutTicks);
/**
* Update the subtitle of titles displayed to the player
*
* @param subtitle Subtitle to set
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated
public void setSubtitle(net.md_5.bungee.api.chat.BaseComponent[] subtitle);
/**
* Update the subtitle of titles displayed to the player
*
* @param subtitle Subtitle to set
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated
public void setSubtitle(net.md_5.bungee.api.chat.BaseComponent subtitle);
/**
* Show the given title to the player, along with the last subtitle set, using the last set times
*
* @param title Title to set
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated
public void showTitle(@Nullable net.md_5.bungee.api.chat.BaseComponent[] title);
/**
* Show the given title to the player, along with the last subtitle set, using the last set times
*
* @param title Title to set
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated
public void showTitle(@Nullable net.md_5.bungee.api.chat.BaseComponent title);
/**
* Show the given title and subtitle to the player using the given times
*
* @param title big text
* @param subtitle little text under it
* @param fadeInTicks ticks to fade-in
* @param stayTicks ticks to stay visible
* @param fadeOutTicks ticks to fade-out
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated
public void showTitle(@Nullable net.md_5.bungee.api.chat.BaseComponent[] title, @Nullable net.md_5.bungee.api.chat.BaseComponent[] subtitle, int fadeInTicks, int stayTicks, int fadeOutTicks);
/**
* Show the given title and subtitle to the player using the given times
*
* @param title big text
* @param subtitle little text under it
* @param fadeInTicks ticks to fade-in
* @param stayTicks ticks to stay visible
* @param fadeOutTicks ticks to fade-out
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated
public void showTitle(@Nullable net.md_5.bungee.api.chat.BaseComponent title, @Nullable net.md_5.bungee.api.chat.BaseComponent subtitle, int fadeInTicks, int stayTicks, int fadeOutTicks);
/**
* Show the title to the player, overriding any previously displayed title.
*
* This method overrides any previous title, use {@link #updateTitle(com.destroystokyo.paper.Title)} to change the existing one. This method doesn't override previous titles, but changes their values.
* If completions were set previously, this method will remove them all and
* replace them with the provided completions.
*
* @param completions the completions to set
*/
public void setCustomChatCompletions(@NotNull Collection
* When using non relative time the player's time will stay fixed at the
* specified time parameter. It's up to the caller to continue updating
* the player's time. To restore player time to normal use
* resetPlayerTime().
*
* @param time The current player's perceived time or the player's time
* offset from the server time.
* @param relative When true the player time is kept relative to its world
* time.
*/
public void setPlayerTime(long time, boolean relative);
/**
* Returns the player's current timestamp.
*
* @return The player's time
*/
public long getPlayerTime();
/**
* Returns the player's current time offset relative to server time, or
* the current player's fixed time if the player's time is absolute.
*
* @return The player's time
*/
public long getPlayerTimeOffset();
/**
* Returns true if the player's time is relative to the server time,
* otherwise the player's time is absolute and will not change its current
* time unless done so with setPlayerTime().
*
* @return true if the player's time is relative to the server time.
*/
public boolean isPlayerTimeRelative();
/**
* Restores the normal condition where the player's time is synchronized
* with the server time.
*
* Equivalent to calling setPlayerTime(0, true).
*/
public void resetPlayerTime();
/**
* Sets the type of weather the player will see. When used, the weather
* status of the player is locked until {@link #resetPlayerWeather()} is
* used.
*
* @param type The WeatherType enum type the player should experience
*/
public void setPlayerWeather(@NotNull WeatherType type);
/**
* Returns the type of weather the player is currently experiencing.
*
* @return The WeatherType that the player is currently experiencing or
* null if player is seeing server weather.
*/
@Nullable
public WeatherType getPlayerWeather();
/**
* Restores the normal condition where the player's weather is controlled
* by server conditions.
*/
public void resetPlayerWeather();
/**
* Gets the player's cooldown between picking up experience orbs.
*
* @return The cooldown in ticks
*/
public int getExpCooldown();
/**
* Sets the player's cooldown between picking up experience orbs..
*
* Note: Setting this to 0 allows the player to pick up
* instantly, but setting this to a negative value will cause the player to
* be unable to pick up xp-orbs.
*
* Calling this Method will result in {@link PlayerExpCooldownChangeEvent}
* being called.
*
* @param ticks The cooldown in ticks
*/
public void setExpCooldown(int ticks);
/**
* Gives the player the amount of experience specified.
*
* @param amount Exp amount to give
*/
public void giveExp(int amount);
/**
* Gives the player the amount of experience levels specified. Levels can
* be taken by specifying a negative amount.
*
* @param amount amount of experience levels to give or take
*/
public void giveExpLevels(int amount);
/**
* Gets the players current experience points towards the next level.
*
* This is a percentage value. 0 is "no progress" and 1 is "next level".
*
* @return Current experience points
*/
public float getExp();
/**
* Sets the players current experience points towards the next level
*
* This is a percentage value. 0 is "no progress" and 1 is "next level".
*
* @param exp New experience points
*/
public void setExp(float exp);
/**
* Gets the players current experience level
*
* @return Current experience level
*/
public int getLevel();
/**
* Sets the players current experience level
*
* @param level New experience level
*/
public void setLevel(int level);
/**
* Gets the players total experience points.
*
* The player's client will download the new texture pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached the same
* texture pack in the past, it will perform a file size check against
* the response content to determine if the texture pack has changed and
* needs to be downloaded again. When this request is sent for the very
* first time from a given server, the client will first display a
* confirmation GUI to the player before proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached the same
* resource pack in the past, it will perform a file size check against
* the response content to determine if the resource pack has changed and
* needs to be downloaded again. When this request is sent for the very
* first time from a given server, the client will first display a
* confirmation GUI to the player before proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI to the player before
* proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI to the player before
* proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI to the player before
* proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI to the player before
* proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI to the player before
* proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI with a custom prompt
* to the player before proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI to the player before
* proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI to the player before
* proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached the same
* resource pack in the past, it will perform a quick timestamp check
* over the network to determine if the resource pack has changed and
* needs to be downloaded again. When this request is sent for the very
* first time from a given server, the client will first display a
* confirmation GUI to the player before proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached the same
* resource pack in the past, it will perform a quick timestamp check
* over the network to determine if the resource pack has changed and
* needs to be downloaded again. When this request is sent for the very
* first time from a given server, the client will first display a
* confirmation GUI to the player before proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached the same
* resource pack in the past, it will perform a quick timestamp check
* over the network to determine if the resource pack has changed and
* needs to be downloaded again. When this request is sent for the very
* first time from a given server, the client will first display a
* confirmation GUI to the player before proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically switch to it once the
* download is complete. If the client has downloaded and cached the same
* resource pack in the past, it will perform a quick timestamp check
* over the network to determine if the resource pack has changed and
* needs to be downloaded again. When this request is sent for the very
* first time from a given server, the client will first display a
* confirmation GUI to the player before proceeding with the download.
*
* Notes:
*
* The player's client will download the new resource pack asynchronously
* in the background, and will automatically add to it once the
* download is complete. If the client has downloaded and cached a
* resource pack with the same hash in the past it will not download but
* directly apply the cached pack. If the hash is null and the client has
* downloaded and cached the same resource pack in the past, it will
* perform a file size check against the response content to determine if
* the resource pack has changed and needs to be downloaded again. When
* this request is sent for the very first time from a given server, the
* client will first display a confirmation GUI to the player before
* proceeding with the download.
*
* Notes:
*
* Displayed health follows a simple formula
* Displayed health follows a simple formula
* No-tick view distance is the view distance where chunks will load, however the chunks and their entities will not
* be set to tick.
*
* No-tick view distance is the view distance where chunks will load, however the chunks and their entities will not
* be set to tick.
*
* Sending view distance is the view distance where chunks will load in for players.
*
* Sending view distance is the view distance where chunks will load in for players.
*
* Note: that this may not always be consistent with the current movement
* of the player.
*
* @return current input
*/
@NotNull
@ApiStatus.Experimental
public Input getCurrentInput();
/**
* Play a note for the player at a location.
* This will work with cake.
*
* @param loc The location to play the note
* @param instrument The instrument ID.
* @param note The note ID.
* @deprecated Magic value
*/
@Deprecated(since = "1.6.2")
public void playNote(@NotNull Location loc, byte instrument, byte note);
/**
* Play a note for the player at a location.
* This will work with cake.
*
* This refers to the total amount of experience the player has collected
* over time and is not currently displayed to the client.
*
* @return Current total experience points
*/
public int getTotalExperience();
/**
* Sets the players current experience points.
*
* This refers to the total amount of experience the player has collected
* over time and is not currently displayed to the client.
*
* @param exp New total experience points
*/
public void setTotalExperience(int exp);
/**
* Send an experience change.
*
* This fakes an experience change packet for a user. This will not actually
* change the experience points in any way.
*
* @param progress Experience progress percentage (between 0.0 and 1.0)
* @see #setExp(float)
*/
public void sendExperienceChange(float progress);
/**
* Send an experience change.
*
* This fakes an experience change packet for a user. This will not actually
* change the experience points in any way.
*
* @param progress New experience progress percentage (between 0.0 and 1.0)
* @param level New experience level
*
* @see #setExp(float)
* @see #setLevel(int)
*/
public void sendExperienceChange(float progress, int level);
/**
* Determines if the Player is allowed to fly via jump key double-tap like
* in creative mode.
*
* @return True if the player is allowed to fly.
*/
public boolean getAllowFlight();
/**
* Sets if the Player is allowed to fly via jump key double-tap like in
* creative mode.
*
* @param flight If flight should be allowed.
*/
public void setAllowFlight(boolean flight);
/**
* Hides a player from this player
*
* @param player Player to hide
* @deprecated see {@link #hidePlayer(Plugin, Player)}
*/
@Deprecated(since = "1.12.2")
public void hidePlayer(@NotNull Player player);
/**
* Hides a player from this player
*
* @param plugin Plugin that wants to hide the player
* @param player Player to hide
*/
public void hidePlayer(@NotNull Plugin plugin, @NotNull Player player);
/**
* Allows this player to see a player that was previously hidden
*
* @param player Player to show
* @deprecated see {@link #showPlayer(Plugin, Player)}
*/
@Deprecated(since = "1.12.2")
public void showPlayer(@NotNull Player player);
/**
* Allows this player to see a player that was previously hidden. If
* another plugin had hidden the player too, then the player will
* remain hidden until the other plugin calls this method too.
*
* @param plugin Plugin that wants to show the player
* @param player Player to show
*/
public void showPlayer(@NotNull Plugin plugin, @NotNull Player player);
/**
* Checks to see if a player has been hidden from this player
*
* @param player Player to check
* @return True if the provided player is not being hidden from this
* player
*/
public boolean canSee(@NotNull Player player);
/**
* Visually hides an entity from this player.
*
* @param plugin Plugin that wants to hide the entity
* @param entity Entity to hide
*/
public void hideEntity(@NotNull Plugin plugin, @NotNull Entity entity);
/**
* Allows this player to see an entity that was previously hidden. If
* another plugin had hidden the entity too, then the entity will
* remain hidden until the other plugin calls this method too.
*
* @param plugin Plugin that wants to show the entity
* @param entity Entity to show
*/
public void showEntity(@NotNull Plugin plugin, @NotNull Entity entity);
/**
* Checks to see if an entity has been visually hidden from this player.
*
* @param entity Entity to check
* @return True if the provided entity is not being hidden from this
* player
*/
public boolean canSee(@NotNull Entity entity);
/**
* Checks to see if this player is currently flying or not.
*
* @return True if the player is flying, else false.
*/
public boolean isFlying();
/**
* Makes this player start or stop flying.
*
* @param value True to fly.
*/
public void setFlying(boolean value);
/**
* Sets the speed at which a client will fly. Negative values indicate
* reverse directions.
*
* @param value The new speed, from -1 to 1.
* @throws IllegalArgumentException If new speed is less than -1 or
* greater than 1
*/
public void setFlySpeed(float value) throws IllegalArgumentException;
/**
* Sets the speed at which a client will walk. Negative values indicate
* reverse directions.
*
* @param value The new speed, from -1 to 1.
* @throws IllegalArgumentException If new speed is less than -1 or
* greater than 1
*/
public void setWalkSpeed(float value) throws IllegalArgumentException;
/**
* Gets the current allowed speed that a client can fly.
*
* @return The current allowed speed, from -1 to 1
*/
public float getFlySpeed();
/**
* Gets the current allowed speed that a client can walk.
*
* @return The current allowed speed, from -1 to 1
*/
public float getWalkSpeed();
/**
* Request that the player's client download and switch texture packs.
*
*
*
* @param url The URL from which the client will download the texture
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long.
* @deprecated Minecraft no longer uses textures packs. Instead you
* should use {@link #setResourcePack(UUID, String, byte[], net.kyori.adventure.text.Component, boolean)}.
*/
@Deprecated(since = "1.7.2")
public void setTexturePack(@NotNull String url);
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @deprecated in favour of {@link #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)}
*/
@Deprecated // Paper - adventure
public void setResourcePack(@NotNull String url);
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @deprecated in favour of {@link #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)}
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
*/
@Deprecated // Paper - adventure
public void setResourcePack(@NotNull String url, @Nullable byte[] hash);
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @deprecated in favour of {@link #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)}
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @param prompt The optional custom prompt message to be shown to client.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
*/
@Deprecated // Paper - adventure
public void setResourcePack(@NotNull String url, @Nullable byte[] hash, @Nullable String prompt);
// Paper start
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @param prompt The optional custom prompt message to be shown to client.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
* @see #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)
*/
default void setResourcePack(final @NotNull String url, final byte @Nullable [] hash, final net.kyori.adventure.text.@Nullable Component prompt) {
this.setResourcePack(url, hash, prompt, false);
}
// Paper end
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @param force If true, the client will be disconnected from the server
* when it declines to use the resource pack.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
* @deprecated in favour of {@link #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)}
*/
@Deprecated // Paper - adventure
public void setResourcePack(@NotNull String url, @Nullable byte[] hash, boolean force);
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @param prompt The optional custom prompt message to be shown to client.
* @param force If true, the client will be disconnected from the server
* when it declines to use the resource pack.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
* @deprecated in favour of {@link #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)}
*/
@Deprecated // Paper
public void setResourcePack(@NotNull String url, @Nullable byte[] hash, @Nullable String prompt, boolean force);
// Paper start
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @param prompt The optional custom prompt message to be shown to client.
* @param force If true, the client will be disconnected from the server
* when it declines to use the resource pack.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
* @see #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)
*/
default void setResourcePack(final @NotNull String url, final byte @Nullable [] hash, final net.kyori.adventure.text.@Nullable Component prompt, final boolean force) {
this.setResourcePack(UUID.nameUUIDFromBytes(url.getBytes(java.nio.charset.StandardCharsets.UTF_8)), url, hash, prompt, force);
}
// Paper end
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param id Unique resource pack ID.
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @param prompt The optional custom prompt message to be shown to client.
* @param force If true, the client will be disconnected from the server
* when it declines to use the resource pack.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
* @deprecated in favour of {@link #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)}
*/
@Deprecated // Paper - adventure
public void setResourcePack(@NotNull UUID id, @NotNull String url, @Nullable byte[] hash, @Nullable String prompt, boolean force);
// Paper start
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param uuid Unique resource pack ID.
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @param prompt The optional custom prompt message to be shown to client.
* @param force If true, the client will be disconnected from the server
* when it declines to use the resource pack.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
* @see #sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest)
*/
void setResourcePack(@NotNull UUID uuid, @NotNull String url, byte @Nullable [] hash, net.kyori.adventure.text.@Nullable Component prompt, boolean force);
// Paper end
// Paper start - more resource pack API
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash A 40 character hexadecimal and lowercase SHA-1 digest of
* the resource pack file.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
*/
default void setResourcePack(final @NotNull String url, final @NotNull String hash) {
this.setResourcePack(url, hash, false);
}
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash A 40 character hexadecimal and lowercase SHA-1 digest of
* the resource pack file.
* @param required Marks if the resource pack should be required by the client
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
*/
default void setResourcePack(final @NotNull String url, final @NotNull String hash, final boolean required) {
this.setResourcePack(url, hash, required, null);
}
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash A 40 character hexadecimal and lowercase SHA-1 digest of
* the resource pack file.
* @param required Marks if the resource pack should be required by the client
* @param resourcePackPrompt A Prompt to be displayed in the client request
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
*/
default void setResourcePack(final @NotNull String url, final @NotNull String hash, final boolean required, final net.kyori.adventure.text.@Nullable Component resourcePackPrompt) {
this.setResourcePack(UUID.nameUUIDFromBytes(url.getBytes(java.nio.charset.StandardCharsets.UTF_8)), url, hash, resourcePackPrompt, required);
}
/**
* Request that the player's client download and switch resource packs.
*
*
*
* @param uuid Unique resource pack ID.
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash A 40 character hexadecimal and lowercase SHA-1 digest of
* the resource pack file.
* @param resourcePackPrompt A Prompt to be displayed in the client request
* @param required Marks if the resource pack should be required by the client
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
*/
default void setResourcePack(final @NotNull UUID uuid, final @NotNull String url, final @NotNull String hash, final net.kyori.adventure.text.@Nullable Component resourcePackPrompt, final boolean required) {
this.sendResourcePacks(net.kyori.adventure.resource.ResourcePackRequest.resourcePackRequest()
.required(required)
.replace(true)
.prompt(resourcePackPrompt)
.packs(net.kyori.adventure.resource.ResourcePackInfo.resourcePackInfo(uuid, java.net.URI.create(url), hash))
);
}
/**
* Gets the most recent resource pack status from the player.
*
* @return the most recent status or null
*/
org.bukkit.event.player.PlayerResourcePackStatusEvent.@Nullable Status getResourcePackStatus();
/**
* Gets the most recent pack hash from the player.
*
* @return the most recent hash or null
* @deprecated This is no longer sent from the client and will always be null
*/
@Deprecated(forRemoval = true, since = "1.13.2")
@org.jetbrains.annotations.Contract("-> null")
default @Nullable String getResourcePackHash() {
return null;
}
/**
* Gets if the last resource pack status from the player
* was {@link org.bukkit.event.player.PlayerResourcePackStatusEvent.Status#SUCCESSFULLY_LOADED}.
*
* @return true if last status was successfully loaded
*/
default boolean hasResourcePack() {
return this.getResourcePackStatus() == org.bukkit.event.player.PlayerResourcePackStatusEvent.Status.SUCCESSFULLY_LOADED;
}
// Paper end - more resource pack API
/**
* Request that the player's client download and include another resource pack.
*
*
*
* @param id Unique resource pack ID.
* @param url The URL from which the client will download the resource
* pack. The string must contain only US-ASCII characters and should
* be encoded as per RFC 1738.
* @param hash The sha1 hash sum of the resource pack file which is used
* to apply a cached version of the pack directly without downloading
* if it is available. Hast to be 20 bytes long!
* @param prompt The optional custom prompt message to be shown to client.
* @param force If true, the client will be disconnected from the server
* when it declines to use the resource pack.
* @throws IllegalArgumentException Thrown if the URL is null.
* @throws IllegalArgumentException Thrown if the URL is too long. The
* length restriction is an implementation specific arbitrary value.
* @throws IllegalArgumentException Thrown if the hash is not 20 bytes
* long.
*/
public void addResourcePack(@NotNull UUID id, @NotNull String url, @Nullable byte[] hash, @Nullable String prompt, boolean force);
/**
* Request that the player's client remove a resource pack sent by the
* server.
*
* @param id the id of the resource pack.
* @throws IllegalArgumentException If the ID is null.
* @see #removeResourcePacks(UUID, UUID...)
*/
public void removeResourcePack(@NotNull UUID id);
/**
* Request that the player's client remove all loaded resource pack sent by
* the server.
* @see #clearResourcePacks()
*/
public void removeResourcePacks();
/**
* Gets the Scoreboard displayed to this player
*
* @return The current scoreboard seen by this player
*/
@NotNull
public Scoreboard getScoreboard();
/**
* Sets the player's visible Scoreboard.
*
* @param scoreboard New Scoreboard for the player
* @throws IllegalArgumentException if scoreboard is null
* @throws IllegalArgumentException if scoreboard was not created by the
* {@link org.bukkit.scoreboard.ScoreboardManager scoreboard manager}
* @throws IllegalStateException if this is a player that is not logged
* yet or has logged out
*/
public void setScoreboard(@NotNull Scoreboard scoreboard) throws IllegalArgumentException, IllegalStateException;
/**
* Gets the {@link WorldBorder} visible to this Player, or null if viewing
* the world's world border.
*
* @return the player's world border
*/
@Nullable
public WorldBorder getWorldBorder();
/**
* Sets the {@link WorldBorder} visible to this Player.
*
* @param border the border to set, or null to set to the world border of
* the player's current world
*
* @throws UnsupportedOperationException if setting the border to that of
* a world in which the player is not currently present.
*
* @see Server#createWorldBorder()
*/
public void setWorldBorder(@Nullable WorldBorder border);
/**
* Send a health update to the player. This will adjust the health, food, and
* saturation on the client and will not affect the player's actual values on
* the server. As soon as any of these values change on the server, changes sent
* by this method will no longer be visible.
*
* @param health the health. If 0.0, the client will believe it is dead
* @param foodLevel the food level
* @param saturation the saturation
*/
public void sendHealthUpdate(double health, int foodLevel, float saturation);
/**
* Send a health update to the player using its known server values. This will
* synchronize the health, food, and saturation on the client and therefore may
* be useful when changing a player's maximum health attribute.
*/
public void sendHealthUpdate();
/**
* Gets if the client is displayed a 'scaled' health, that is, health on a
* scale from 0-{@link #getHealthScale()}.
*
* @return if client health display is scaled
* @see Player#setHealthScaled(boolean)
*/
public boolean isHealthScaled();
/**
* Sets if the client is displayed a 'scaled' health, that is, health on a
* scale from 0-{@link #getHealthScale()}.
* displayedHealth =
* getHealth() / getMaxHealth() * getHealthScale().
*
* @param scale if the client health display is scaled
*/
public void setHealthScaled(boolean scale);
/**
* Sets the number to scale health to for the client; this will also
* {@link #setHealthScaled(boolean) setHealthScaled(true)}.
* displayedHealth =
* getHealth() / getMaxHealth() * getHealthScale().
*
* @param scale the number to scale health to
* @throws IllegalArgumentException if scale is <0
* @throws IllegalArgumentException if scale is {@link Double#NaN}
* @throws IllegalArgumentException if scale is too high
*/
public void setHealthScale(double scale) throws IllegalArgumentException;
/**
* Gets the number that health is scaled to for the client.
*
* @return the number that health would be scaled to for the client if
* HealthScaling is set to true
* @see Player#setHealthScale(double)
* @see Player#setHealthScaled(boolean)
*/
public double getHealthScale();
/**
* Gets the entity which is followed by the camera when in
* {@link GameMode#SPECTATOR}.
*
* @return the followed entity, or null if not in spectator mode or not
* following a specific entity.
*/
@Nullable
public Entity getSpectatorTarget();
/**
* Sets the entity which is followed by the camera when in
* {@link GameMode#SPECTATOR}.
*
* @param entity the entity to follow or null to reset
* @throws IllegalStateException if the player is not in
* {@link GameMode#SPECTATOR}
*/
public void setSpectatorTarget(@Nullable Entity entity);
/**
* Sends a title and a subtitle message to the player. If either of these
* values are null, they will not be sent and the display will remain
* unchanged. If they are empty strings, the display will be updated as
* such. If the strings contain a new line, only the first line will be
* sent. The titles will be displayed with the client's default timings.
*
* @param title Title text
* @param subtitle Subtitle text
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated(since = "1.8.7")
public void sendTitle(@Nullable String title, @Nullable String subtitle);
/**
* Sends a title and a subtitle message to the player. If either of these
* values are null, they will not be sent and the display will remain
* unchanged. If they are empty strings, the display will be updated as
* such. If the strings contain a new line, only the first line will be
* sent. All timings values may take a value of -1 to indicate that they
* will use the last value sent (or the defaults if no title has been
* displayed).
*
* @param title Title text
* @param subtitle Subtitle text
* @param fadeIn time in ticks for titles to fade in. Defaults to 10.
* @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.
* @deprecated Use {@link #showTitle(net.kyori.adventure.title.Title)} or {@link #sendTitlePart(net.kyori.adventure.title.TitlePart, Object)}
*/
@Deprecated // Paper - Adventure
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
* title / subtitle and reset timings to their default values.
*/
public void resetTitle();
/**
* Spawns the particle (the number of times specified by count)
* at the target location.
*
* @param particle the particle to spawn
* @param location the location to spawn at
* @param count the number of particles
*/
public void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count);
/**
* Spawns the particle (the number of times specified by count)
* at the target location.
*
* @param particle the particle to spawn
* @param x the position on the x axis to spawn at
* @param y the position on the y axis to spawn at
* @param z the position on the z axis to spawn at
* @param count the number of particles
*/
public void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count);
/**
* Spawns the particle (the number of times specified by count)
* at the target location.
*
* @param
* Will default to the server view distance if the client has not yet
* communicated this information,
*
* @return client view distance as above
*/
public int getClientViewDistance();
// Paper start
/**
* Gets the player's current locale.
*
* @return the player's locale
*/
@NotNull java.util.Locale locale();
// Paper end
/**
* Gets the player's estimated ping in milliseconds.
*
* In Vanilla this value represents a weighted average of the response time
* to application layer ping packets sent. This value does not represent the
* network round trip time and as such may have less granularity and be
* impacted by other sources. For these reasons it should not be used
* for anti-cheat purposes. Its recommended use is only as a
* qualitative indicator of connection quality (Vanilla uses it for
* this purpose in the tab list).
*
* @return player ping
*/
public int getPing();
/**
* Gets the player's current locale.
*
* The value of the locale String is not defined properly.
*
* The vanilla Minecraft client will use lowercase language / country pairs
* separated by an underscore, but custom resource packs may use any format
* they wish.
*
* @return the player's locale
* @deprecated in favour of {@link #locale()}
*/
@NotNull
@Deprecated // Paper
public String getLocale();
// Paper start
/**
* Get whether the player can affect mob spawning
*
* @return if the player can affect mob spawning
*/
public boolean getAffectsSpawning();
/**
* Set whether the player can affect mob spawning
*
* @param affects Whether the player can affect mob spawning
*/
public void setAffectsSpawning(boolean affects);
/**
* Gets the view distance for this player
*
* @return the player's view distance
* @see org.bukkit.World#getViewDistance()
*/
public int getViewDistance();
/**
* Sets the view distance for this player
*
* @param viewDistance the player's view distance
* @see org.bukkit.World#setViewDistance(int)
*/
public void setViewDistance(int viewDistance);
/**
* Gets the simulation distance for this player
*
* @return the player's simulation distance
*/
public int getSimulationDistance();
/**
* Sets the simulation distance for this player
*
* @param simulationDistance the player's new simulation distance
*/
public void setSimulationDistance(int simulationDistance);
/**
* Gets the no-ticking view distance for this player.
*
* Generally useful to ensure the client has a complete list of commands
* after permission changes are done.
*/
public void updateCommands();
/**
* Open a {@link Material#WRITTEN_BOOK} for a Player
*
* @param book The book to open for this player
*/
public void openBook(@NotNull ItemStack book);
/**
* Open a Sign for editing by the Player.
*
* The Sign must be placed in the same world as the player.
*
* @param sign The sign to edit
*/
public void openSign(@NotNull Sign sign);
/**
* Open a Sign for editing by the Player.
*
* The Sign must be placed in the same world as the player.
*
* @param sign The sign to edit
* @param side The side to edit
*/
public void openSign(@NotNull Sign sign, @NotNull Side side);
/**
* Shows the demo screen to the player, this screen is normally only seen in
* the demo version of the game.
*
* Servers can modify the text on this screen using a resource pack.
*/
public void showDemoScreen();
/**
* Gets whether the player has the "Allow Server Listings" setting enabled.
*
* @return whether the player allows server listings
*/
public boolean isAllowingServerListings();
// Paper start
@NotNull
@Override
default net.kyori.adventure.text.event.HoverEvent