Interface Player

All Superinterfaces:
Audience, BossBarViewer, CommandSender, Entity, HoverEventSource<HoverEvent.ShowEntity>, Identified, LivingEntity, ObjectContentsLike, PermissionHolder, Pointered, SchedulerSource, Sound.Emitter, Sound.Source.Provider
public interface Player extends LivingEntity, CommandSender, Identified, BossBarViewer, ObjectContentsLike
Represents a player currently connected to the server.

A Player reference is not stable across the server lifecycle, as entering the CONFIGURATION phase (see enterConfigurationPhase()) discards the underlying player and recreates it, which invalidates every reference held before that point. Player references should not be cached, as a reference obtained from an event or lookup is only guaranteed valid for the duration of that call. Instead, re-fetch by UUID or name via PlayerManager.get(UUID) or PlayerManager.get(String).

Since:
0.1.0

  • Method Details

    • refreshCommands

      void refreshCommands()
      Resends the command tree to the client, after permissions or registered commands changed.
      Since:
      0.1.0

    • profile

      PlayerProfile profile()
      Returns the identity and skin of this player.
      Returns:
      the identity and skin of this player
      Since:
      0.1.0

    • offline

      default OfflinePlayer offline()
      Gets the offline handle for this player's identity.
      Returns:
      the handle for this player's identity
      Since:
      0.1.0

    • identity

      default Identity identity()
      Specified by:
      identity in interface Identified

    • uuid

      default UUID uuid()
      Description copied from interface: Entity
      Returns the persistent identity of this entity.
      Specified by:
      uuid in interface Entity
      Returns:
      the persistent identity of this entity

    • name

      default String name()
      Description copied from interface: CommandSender
      Returns the name of this sender.
      Specified by:
      name in interface CommandSender
      Returns:
      the name of this sender

    • address

      InetAddress address()
      Gets the address this player is connected from.
      Returns:
      the client address
      Throws:
      IllegalStateException - if the connection has no resolvable IP address
      Since:
      0.1.0

    • ping

      int ping()
      Gets the round-trip time between the server and this player's client.
      Returns:
      the round-trip time in milliseconds
      Since:
      0.1.0

    • kick

      void kick(Component reason)
      Disconnects this player.
      Parameters:
      reason - the message shown on the disconnection screen
      Since:
      0.1.0

    • inventory

      PlayerInventory inventory()
      Returns the inventory this player carries; call updateInventory() after changing it.
      Returns:
      the inventory this player carries; call updateInventory() after changing it
      Since:
      0.1.0

    • enderChest

      EnderChestInventory enderChest()
      Returns the ender chest of this player.
      Returns:
      the ender chest of this player
      Since:
      0.1.0

    • selectedSlot

      int selectedSlot()
      Returns:
      the hotbar slot (0-8) currently selected by this player
      Since:
      0.1.0

    • setSelectedSlot

      void setSelectedSlot(int slot)
      Parameters:
      slot - the hotbar slot to select, 0-8
      Throws:
      IllegalArgumentException - if slot is out of [0, 8]
      Since:
      0.1.0

    • input

      PlayerInput input()
      Returns the movement keys this player is holding, as last reported by their client.
      Returns:
      the movement keys this player is holding, as last reported by their client
      Since:
      0.1.0

    • eyeHeight

      double eyeHeight()
      Returns how high above their feet this player's eyes are, lower while sneaking.
      Returns:
      how high above their feet this player's eyes are, lower while sneaking

    • setAttributeBase

      void setAttributeBase(TypedKey<Attribute> attribute, double base)
      Changes the base value of an attribute for this player.

      The player's client applies it at once: a movement speed of 0 stops them from walking, a block interaction range of 0 from reaching any block. The value is kept until it is reset or the player disconnects, including across respawns and world changes. The client clamps it to the range of the attribute.

      Parameters:
      attribute - the attribute, see AttributeKeys
      base - the new base value
      Throws:
      IllegalArgumentException - if the attribute does not exist or base is not finite
      Since:
      0.1.0

    • resetAttributeBase

      void resetAttributeBase(TypedKey<Attribute> attribute)
      Gives an attribute back the base value a vanilla player has.

      Does nothing when the base value was not changed.

      Parameters:
      attribute - the attribute, see AttributeKeys
      Throws:
      IllegalArgumentException - if the attribute does not exist
      Since:
      0.1.0

    • attributeBase

      OptionalDouble attributeBase(TypedKey<Attribute> attribute)
      Returns the base value set for an attribute.
      Parameters:
      attribute - the attribute, see AttributeKeys
      Returns:
      the value given to setAttributeBase(TypedKey, double), or empty when the attribute has the base value a vanilla player has
      Since:
      0.1.0

    • heldItem

      default ItemStack heldItem()
      Returns:
      the stack in the currently selected hotbar slot, never null (ItemStack.EMPTY when nothing is held)
      Since:
      0.1.0

    • setHeldItem

      default void setHeldItem(@Nullable ItemStack stack)
      Replaces the stack in the currently selected hotbar slot.
      Parameters:
      stack - the new stack, null is normalized to ItemStack.EMPTY
      Since:
      0.1.0

    • gameMode

      GameMode gameMode()
      Returns the current game mode of this player.
      Returns:
      the current game mode of this player
      Since:
      0.1.0

    • setGameMode

      void setGameMode(GameMode gameMode)
      Changes the game mode of this player.
      Parameters:
      gameMode - the new game mode
      Since:
      0.1.0

    • abilities

      PlayerAbilities abilities()
      Returns the abilities of this player.
      Returns:
      the abilities of this player
      Since:
      0.1.0

    • setAbilities

      CompletableFuture<Boolean> setAbilities(PlayerAbilities abilities)
      Changes the abilities of this player, on its own thread.
      Parameters:
      abilities - the new abilities
      Returns:
      a future completing with true once applied, or false if the player was removed
      Since:
      0.1.0

    • isAwaitingRespawn

      boolean isAwaitingRespawn()
      Returns:
      true while this player is dead and still on the respawn screen
      Since:
      0.1.0

    • respawn

      CompletableFuture<Boolean> respawn()
      Respawns this player, exactly as if they had clicked the button on the death screen.

      The respawn is queued on the region owning the player and happens on the next tick, so it is safe to call from a PlayerDeathEvent listener to skip the death screen entirely. The player comes back at their respawn point, or at the world spawn when they have none, and a PlayerRespawnEvent is fired as usual.

      Returns:
      a future completing with true once the player has actually been moved to their respawn point, or false if the respawn was refused (the player is not waiting to respawn or has left the server) or the move to the respawn point failed
      Since:
      0.1.0

    • respawnPoint

      @Nullable RespawnPoint respawnPoint()
      Returns:
      where this player respawns, or null when they use the world spawn
      Since:
      0.1.0

    • setRespawnPoint

      void setRespawnPoint(@Nullable RespawnPoint point)
      Sets where this player respawns. The point is saved with the rest of their data and restored on their next login.
      Parameters:
      point - the point to respawn at, or null to fall back to the world spawn
      Since:
      0.1.0

    • setRespawnPoint

      default void setRespawnPoint(World world, Location location)
      Parameters:
      world - the world to respawn in
      location - the position to respawn at
      Since:
      0.1.0

    • setRespawnPoint

      default void setRespawnPoint(Location location)
      Parameters:
      location - the position to respawn at, in the player's current world
      Since:
      0.1.0

    • enterConfigurationPhase

      CompletableFuture<Boolean> enterConfigurationPhase()
      Switches this player's connection state from PLAY to CONFIGURATION. Useful for resending data synced during the CONFIGURATION phase.
      Returns:
      a future completing with true once the player's data is saved and the client has been told to switch, or false if the player is already switching, not in play, or cannot be switched
      Since:
      0.1.0
      API Note:
      This removes the player from the world fully and creates them anew, firing PlayerQuitEvent, PlayerJoinEvent, and saving their data to disk. Any reference to this Player held before this call should be considered stale.

    • updateInventory

      void updateInventory()
      Updates the player's inventory on the client side.

      This is useful when the server has changed the inventory contents, and the client needs to be informed of those changes. This method should be called after any modifications to the player's inventory, such as adding or removing items, to ensure that the client sees the correct state.

      Since:
      0.1.0

    • activePostEffects

      @Contract(pure=true) @Unmodifiable List<Key> activePostEffects()
      Returns the active post effects, in order.
      Returns:
      the active post effects, in order
      Since:
      0.1.0

    • setActivePostEffects

      CompletableFuture<Boolean> setActivePostEffects(SequencedCollection<Key> effects)
      Replaces the currently active post effects.
      Parameters:
      effects - the post effect keys, in order
      Returns:
      a future completing with true if the active post effects changed, or false if they were already effects, the change was cancelled, or the player left first
      Since:
      0.1.0

    • activatePostEffect

      CompletableFuture<Boolean> activatePostEffect(Key effect)
      Activates a post effect if it is not already active, adding it to the end of the list.
      Parameters:
      effect - the post effect key
      Returns:
      a future completing with true if it was activated, or false if it was already active, the change was cancelled, or the player left first
      Since:
      0.1.0

    • deactivatePostEffect

      CompletableFuture<Boolean> deactivatePostEffect(Key effect)
      Deactivates a post effect if it is active.
      Parameters:
      effect - the post effect key
      Returns:
      a future completing with true if it was deactivated, or false if it was not active, the change was cancelled, or the player left first
      Since:
      0.1.0

    • clearActivePostEffects

      CompletableFuture<Boolean> clearActivePostEffects()
      Deactivates every active post effect.
      Returns:
      a future completing with true if any post effect was deactivated, or false if none were active, the change was cancelled, or the player left first
      Since:
      0.1.0

    • commandSource

      default CommandSource commandSource()
      Description copied from interface: CommandSender
      Returns the source a command run by this sender starts from.
      Specified by:
      commandSource in interface CommandSender
      Returns:
      the source a command run by this sender starts from