* Note that this name will not be displayed in game, only in chat and * places defined by plugins. * * @return the friendly name */ @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. */ 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(); /** * 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 */ 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(); /** * Gets the currently displayed player list footer for this player. * * @return player list header or null */ @Nullable public String getPlayerListFooter(); /** * Sets the currently displayed player list header for this player. * * @param header player list header, null for empty */ 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(@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 */ 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(); /** * Sends this sender a message raw * * @param message Message to be displayed */ @Override public void sendRawMessage(@NotNull String message); /** * Kicks player with custom kick message. * * @param message kick message */ public void kickPlayer(@Nullable String message); /** * Says a message (or runs a command). * * @param msg message to print */ public void chat(@NotNull String msg); /** * Makes the player perform the given command * * @param command Command to perform * @return true if the command was successful, otherwise false */ public boolean performCommand(@NotNull String command); /** * Returns true if the entity is supported by a block. * * This value is a state updated by the client after each movement. * * @return True if entity is on ground. * @deprecated This value is controlled only by the client and is therefore * unreliable and vulnerable to spoofing and/or desync depending on the * context/time which it is accessed */ @Override @Deprecated public boolean isOnGround(); /** * Returns if the player is in sneak mode * * @return true if player is in sneak mode */ public boolean isSneaking(); /** * Sets the sneak mode the player * * @param sneak true if player should appear sneaking */ public void setSneaking(boolean sneak); /** * Gets whether the player is sprinting or not. * * @return true if player is sprinting. */ public boolean isSprinting(); /** * Sets whether the player is sprinting or not. * * @param sprinting true if the player should be sprinting */ public void setSprinting(boolean sprinting); /** * Saves the players current location, health, inventory, motion, and * other information into the username.dat file, in the world/player * folder */ public void saveData(); /** * Loads the players current location, health, inventory, motion, and * other information from the username.dat file, in the world/player * folder. *
* 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. */ @Nullable @Override public Location getBedSpawnLocation(); /** * Sets the Location where the player will spawn at their bed. * * @param location where to set the respawn location */ public void setBedSpawnLocation(@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 */ public void setBedSpawnLocation(@Nullable Location location, boolean force); /** * Play a note for a player at a location. This requires a note block * at the particular location (as far as the client is concerned). This * will not work without a note block. This will not work with cake. * * @param loc The location of a note block. * @param instrument The instrument ID. * @param note The note ID. * @deprecated Magic value */ @Deprecated public void playNote(@NotNull Location loc, byte instrument, byte note); /** * Play a note for a player at a location. This requires a note block * at the particular location (as far as the client is concerned). This * will not work without a note block. This will not work with cake. * * @param loc The location of a note block * @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 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);
/**
* 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
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
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
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
*/
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.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
*/
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.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 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
*/
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.Material, byte)}.
*
* 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;
/**
* 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);
/**
* Send a hurt animation. This fakes incoming damage towards the player from
* the given yaw relative to the player's direction.
*
* @param yaw the yaw in degrees relative to the player's direction where 0
* is in front of the player, 90 is to the right, 180 is behind, and 270 is
* to the left
*/
public void sendHurtAnimation(float yaw);
/**
* Add custom chat completion suggestions shown to the player while typing a
* message.
*
* @param completions the completions to send
*/
public void addCustomChatCompletions(@NotNull Collection
* 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:
*
* Displayed health follows a simple formula
* Displayed health follows a simple formula
* 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
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
public void showPlayer(@NotNull Player player);
/**
* Allows this player to see a player that was previously hidden. If
* another 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
* @apiNote draft API
*/
@ApiStatus.Experimental
public void hideEntity(@NotNull Plugin plugin, @NotNull Entity entity);
/**
* Allows this player to see an entity that was previously hidden. If
* another 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
* @apiNote draft API
*/
@ApiStatus.Experimental
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
* @apiNote draft API
*/
@ApiStatus.Experimental
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(String)}.
*/
@Deprecated
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.
*/
public void setResourcePack(@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.
* @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.
*/
public void setResourcePack(@NotNull String url, @Nullable byte[] hash);
/**
* 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.
*/
public void setResourcePack(@NotNull String url, @Nullable byte[] hash, @Nullable String prompt);
/**
* 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.
*/
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.
*/
public void setResourcePack(@NotNull String url, @Nullable byte[] hash, @Nullable String prompt, boolean force);
/**
* 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);
/**
* 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 API behavior subject to change
*/
@Deprecated
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.
*/
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();
/**
* 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
*/
@NotNull
public String getLocale();
/**
* Update the list of commands sent to the client.
*
* 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();
}