Interface Player

All Superinterfaces:
Audience, BossBarViewer, CommandSender, Entity, HoverEventSource<HoverEvent.ShowEntity>, Identified, LivingEntity, ObjectContentsLike, PermissionHolder, Pointered, SchedulerSource, Sound.Emitter, Sound.Source.Provider

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
  • Field Details

  • 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
    • transfer

      void transfer(String host, int port)
      Sends this player to another server, as /transfer does.

      The client leaves this server on its own and connects to host:port, telling it that it is being transferred. The target server must accept transfers, or the player is turned away there.

      Parameters:
      host - the hostname or IP address of the target server
      port - the port of the target server, from 1 to 65535
      Throws:
      IllegalArgumentException - if host is null or port is out of range
      Since:
      0.1.0
    • isTransferred

      boolean isTransferred()
      Checks whether this player joined through a transfer from another server, rather than by connecting directly.

      Anything can claim to be a transfer: when it matters, check where the player comes from with your own means.

      Returns:
      true if the client announced a transfer when it connected
      Since:
      0.1.0
    • storeCookie

      void storeCookie(Key key, byte[] payload)
      Stores a cookie on this player's client, replacing any cookie stored under the same key.

      The client keeps its cookies for the current session only: they follow the player through transfers, so the next server can read them back, and are lost when the player disconnects. The client can send back anything, so sign a cookie (an HMAC with a secret shared by your servers, for instance) when you need to trust it.

      Parameters:
      key - the identifier of the cookie
      payload - the content of the cookie, at most MAX_COOKIE_SIZE bytes; it is copied
      Throws:
      IllegalArgumentException - if key or payload is null, or if the payload is larger than MAX_COOKIE_SIZE bytes
      Since:
      0.1.0
    • retrieveCookie

      CompletableFuture<Optional<byte[]>> retrieveCookie(Key key)
      Asks this player's client for a cookie, stored by this server or by the one that transferred the player here.

      The future completes on the network thread: do not block it, and hand any work on the world over to the right thread. To check a cookie before the player joins, use PlayerLoginAttemptEvent.retrieveCookie(Key, Consumer) instead.

      Parameters:
      key - the identifier of the cookie
      Returns:
      a future completed with the content of the cookie, or with an empty optional if the client has none; it completes exceptionally if the player disconnects before answering
      Throws:
      IllegalArgumentException - if key is null
      Since:
      0.1.0
    • sendPluginMessage

      void sendPluginMessage(Key channel, byte[] data)
      Sends a plugin message to this player's client, or to the proxy in front of the server, which reads it on the player's connection.

      Any channel works, without declaring it first. The other side ignores the channels it does not listen to: pluginChannels() tells which ones it announced.

      Parameters:
      channel - the channel
      data - the content of the message, at most PluginMessenger.MAX_SENT_SIZE bytes; it is copied
      Throws:
      IllegalArgumentException - if channel or data is null, if the data is too large, or if the channel is PluginMessenger.REGISTER or PluginMessenger.UNREGISTER
      Since:
      0.1.0
      See Also:
    • pluginChannels

      Set<Key> pluginChannels()
      Gets the channels this player's client, and the proxy in front of the server, announced they listen to.
      Returns:
      the channels, as they are now
      Since:
      0.1.0
    • clientBrand

      Optional<String> clientBrand()
      Gets the brand the client announced: the name it gives itself, such as that of its mod loader.
      Returns:
      the brand, or empty if the client did not announce one
      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
    • experienceLevel

      int experienceLevel()
      Returns the experience level of this player., the number shown above the experience bar
      Returns:
      the experience level of this player
      Since:
      0.1.0
    • experienceProgress

      float experienceProgress()
      Returns how far this player is towards the next level., from 0 to 1 excluded: how full the experience bar is
      Returns:
      how far this player is towards the next level
      Since:
      0.1.0
    • totalExperience

      int totalExperience()
      Returns every experience point this player gained since they last lost their experience.
      Returns:
      every experience point this player gained since they last lost their experience
      Since:
      0.1.0
    • experienceForNextLevel

      int experienceForNextLevel()
      Returns how many experience points take this player from their level to the next.

      As in Vanilla: 7 + 2 * level below level 15, 37 + 5 * (level - 15) below level 30, 112 + 9 * (level - 30) from there on.

      Returns:
      how many experience points take this player from their level to the next
      Since:
      0.1.0
    • giveExperience

      void giveExperience(int points)
      Gives this player experience points, or takes some with a negative amount; the level follows.
      Parameters:
      points - how many experience points to give
      Since:
      0.1.0
    • giveExperienceLevels

      void giveExperienceLevels(int levels)
      Gives this player whole levels, or takes some with a negative amount; the experience bar stays as full as it was. Every fifth level reached rings.
      Parameters:
      levels - how many levels to give
      Since:
      0.1.0
    • setExperience

      void setExperience(int level, float progress)
      Sets the experience of this player.
      Parameters:
      level - the experience level, not negative
      progress - how far towards the next level, from 0 to 1 excluded
      Throws:
      IllegalArgumentException - if level is negative
      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

      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